insitupy.plotting.volcano

Contents

insitupy.plotting.volcano#

insitupy.plotting.volcano(results, significance_threshold=0.05, foldchange_threshold=2, pval_col='padj', logfoldchanges_col='log2foldchange', label_top_n=20, label_sortby='log2foldchange', figsize=(6, 6), show=True, show_config=False, title=None, savepath=None, save_only=False, dpi_save=300, xlim=None)#

Generate multi-panel volcano plots for differential expression results.

Creates a comprehensive visualization of differential gene expression analysis, including the main comparison and optional neighborhood comparisons if available in the results object.

Parameters:

  • results (DiffExprResults) – Container object holding differential expression results with: - main: primary comparison results - target_neighborhood: target neighborhood comparison (optional) - ref_neighborhood: reference neighborhood comparison (optional)

  • significance_threshold (Number, default=0.05) – Adjusted p-value threshold for statistical significance.

  • foldchange_threshold (Number, default=2) – Minimum absolute fold change (not log-transformed) for biological significance.

  • label_top_n (int, default=20) – Number of top differentially expressed genes to label in each plot.

  • label_sortby (str, default='log2foldchange') – Column name used to rank genes for labeling. Must be present in the results DataFrame.

  • figsize (tuple of Number, default=(6, 6)) – Size of each subplot in inches (width, height). Total figure width will be figsize[0] * number_of_panels.

  • show (bool, default=True) – If True, displays the plot after creation.

  • show_config (bool, default=False) – If True, displays a configuration table below the main plot showing analysis parameters and DEG counts.

  • title (str, optional) – Overall title for the figure. If None, no title is displayed.

  • savepath (str, os.PathLike, Path, optional) – Path to save the figure. If None, figure is not saved.

  • save_only (bool, default=False) – If True, saves the figure without displaying it (overrides show).

  • dpi_save (int, default=300) – Resolution in dots per inch for saved figure.

Returns:

Displays and/or saves the multi-panel volcano plot as specified.

Return type:

None

Raises:

ValueError – If parameters are out of valid range.

Notes

The function creates 1-3 subplots depending on available data: - Panel 1 (always present): Main comparison volcano plot - Panel 2 (if available): Target neighborhood comparison - Panel 3 (if available): Reference neighborhood comparison

Neighborhood comparisons show genes that are downregulated in the neighborhood compared to the cell type of interest (log2FC < 0), using adjusted p-values with a fold change threshold of 1 (no fold change filtering beyond significance).

Examples

>>> volcano(
...     results=deg_results,
...     significance_threshold=0.01,
...     foldchange_threshold=1.5,
...     label_top_n=15,
...     show_config=True,
...     title="Cell Type A vs Cell Type B"
... )

>>> # Save without displaying
>>> volcano(
...     results=deg_results,
...     savepath="volcano_plots.png",
...     save_only=True,
...     dpi_save=600
... )
Contents