histogram_plot()

Create histogram plot(s) for single or multiple conditions.

Usage

Source

histogram_plot(
    df,
    feature,
    conditions,
    condition_col="condition",
    selector_col=None,
    selector_val=None,
    axes=None,
    title=None,
    show_title=False,
    colors=None,
    fig_size=None,
    size_units="cm",
    bins=100,
    log_scale=False,
    log_base=2,
    x_limits=None,
    normalize=False,
    kde_overlay=False,
    kde_smoothing=0.8,
    kde_params=None,
    show_x_labels=True,
    rotation=0,
    save=False,
    path=None,
    tight_layout=False,
    file_format="pdf",
    dpi=300
)

This function creates histograms using seaborn.histplot with support for log scaling, custom binning, normalization, and KDE overlays.

  • If conditions is a string: Creates single histogram for that condition
  • If conditions is a list: Creates subplots with one histogram per condition

Data Filtering df : pd.DataFrame The dataframe containing the data to plot. feature : str The column name to create histogram for. conditions : str | list[str] Single condition (string) or multiple conditions (list) to plot. condition_col : str, default=“condition” The column name for condition labels. selector_col : Optional[str], default=None The column name for additional filtering. selector_val : Optional[str], default=None The value to filter by if selector_col is provided.

Display Options ^ bins : int | str, default=100 Number of bins or binning strategy. Default is 100 bins. Can be int for exact number or str for methods like “auto”, “sturges”, etc. For multiple conditions with int bins, calculates unified bin edges across all conditions for consistent visualization. log_scale : bool, default=False Whether to use logarithmic scaling for x-axis. log_base : float, default=2 Base for logarithmic scaling (only used if log_scale=True). x_limits : tuple[float, float] | None, default=None X-axis limits as (min, max). If None, uses data range. normalize : bool, default=False Whether to normalize histogram to show density instead of counts. kde_overlay : bool, default=False Whether to overlay KDE curves. When True, shows only KDE lines (no histograms) in a single plot with different colors for each condition. kde_smoothing : float, default=0.8 KDE smoothing factor (bw_adjust parameter). Lower = smoother curves. Typical range: 0.5 (very smooth) to 2.0 (more detailed). kde_params : dict[str, Any] | None, default=None Additional KDE parameters. Common options: - bw_method: ‘scott’ (default), ‘silverman’, or float for manual bandwidth - gridsize: int (default 200) - higher = smoother curves - cut: float (default 2) - how far to extend beyond data range show_x_labels : bool, default=True Whether to show x-axis tick labels. rotation : int, default=0 Rotation angle for x-axis tick labels. axes : Optional[Axes], default=None The matplotlib axes to plot on. Only valid for single condition (string). For multiple conditions, creates subplots automatically.

Styling & Colors title : Optional[str], default=None The title of the plot. If None, auto-generates from feature and condition. show_title : bool, default=False Whether to display the title. When True, positions title at y-axis start. colors : list[str] | None, default=None Colors to use for the histogram. Uses first color in list. fig_size : tuple[float, float] | None, default=None The size of the figure in the specified units. If None, uses dynamic defaults: - Single condition: (4, 4) cm - Multiple conditions: (4 * num_conditions, 4) cm size_units : str, default=“cm” The units for figure size (“cm” or “inches”). tight_layout : bool, default=False Whether to use tight layout when saving.

Save Options save : bool, default=False Whether to save the plot to file. path : Optional[Path], default=None Directory path for saving the plot (required if save=True). file_format : str, default=“pdf” File format for saved plot (“pdf”, “png”, “svg”, etc.). dpi : int, default=300 Resolution for saved plot in dots per inch.

tuple[Figure, Axes | list[Axes]] The matplotlib Figure and Axes object(s). Returns: - (Figure, Axes) for single condition (string input) - (Figure, list[Axes]) for multiple conditions (list input)

ValueError If required parameters are missing or invalid. If specified columns are not found in dataframe. If no data remains after filtering.

>>> # Basic histogram for one condition
>>> fig, ax = histogram_plot(
...     df=df,
...     feature="integrated_int_DAPI_norm",
...     condition="control"
... )
>>> # Log-scale histogram with KDE overlay
>>> fig, ax = histogram_plot(
...     df=df,
...     feature="integrated_int_DAPI_norm",
...     condition="control",
...     log_scale=True,
...     log_base=2,
...     kde_overlay=True,
...     x_limits=(1, 16)
... )
>>> # Histogram with custom styling
>>> fig, ax = histogram_plot(
...     df=df,
...     feature="area_nucleus",
...     condition="treatment1",
...     colors=["#1f77b4"],
...     title="Nucleus Area Distribution - Treatment 1",
...     bins=50,
...     normalize=True
... )
>>> # Multiple histograms using subplots
>>> fig, axes = plt.subplots(1, 3, figsize=(15, 5))
>>> conditions = ["control", "treatment1", "treatment2"]
>>> for i, condition in enumerate(conditions):
...     histogram_plot(
...         df=df,
...         feature="integrated_int_DAPI_norm",
...         condition=condition,
...         axes=axes[i],
...         title=f"Histogram: {condition}"
...     )

This function creates histograms for single conditions. For multiple histograms: - Use this function multiple times with different axes - Use combplot functionality for complex layouts - Create subplots manually and pass axes parameter

The function is designed for flexibility - it can integrate with existing plots by accepting an axes parameter, or create standalone plots when axes=None.

For DNA content histograms (common in cell cycle analysis), consider: - Using log_scale=True with log_base=2 - Setting x_limits based on expected DNA content range - Using normalize=True for comparing different sample sizes