.volcano_plot

proteopy.utils.volcano_plot(fc_vals, pvals, fc_thresh=None, pval_thresh=None, *, labels=None, top_labels=None, highlight_labels=None, figsize=(6.0, 5.0), xlabel=None, ylabel=None, alt_color=None, yscale_log=True, title=None, show=True, save=None, ax=None)[source]

Volcano plot renderer (framework-agnostic).

Draws a scatter plot of fold change (x-axis) versus p-value (y-axis). Points are colored by significance or by an optional alternative boolean mask.

Parameters:

  • fc_vals (Sequence[float] | np.ndarray) – Fold change values (x-axis).

  • pvals (Sequence[float] | np.ndarray) – P-values (y-axis). Must be same length as fc_vals.

  • fc_thresh (float | None, optional) – Absolute fold change threshold for significance. When None, the fold change requirement for significance coloring is dropped. Threshold line is not drawn.

  • pval_thresh (float | None, optional) – P-value threshold for significance. When None, the p-value requirement for significance coloring is dropped. Threshold line is not drawn. When both thresholds are None, all points are colored as significant (blue for negative FC, red for positive FC).

  • labels (Sequence[str] | np.ndarray | None, optional) – Labels for each point, same length as fc_vals. Required when top_labels is set.

  • top_labels (int | None, optional) – Number of top proteins to label per side (up to 2N total). Ranked by smallest p-value, then largest |fc|.

  • highlight_labels (Sequence[str] | None, optional) – Sequence of label strings to highlight on the plot. Each entry must match a value in labels. Matched points are annotated with their label and a connecting arrow. Labels not found after filtering trigger a warning.

  • figsize (tuple[float, float], optional) – Figure dimensions (width, height) in inches.

  • xlabel (str | None, optional) – X-axis label. Defaults to "logFC" when None.

  • ylabel (str | None, optional) – Y-axis label. When None, defaults to "pval" if yscale_log=True or "-log10(pval)" if yscale_log=False.

  • alt_color (list[bool] | np.ndarray | None, optional) – Boolean mask (same length as fc_vals) for alternative coloring. True entries are colored purple, False gray. Overrides significance-based coloring.

  • yscale_log (bool, optional) – When True, plot raw p-values on a log10-scaled inverted y-axis. When False, plot -log10(pval) on a linear y-axis.

  • title (str | None, optional) – Plot title. If None, no title is set.

  • show (bool, optional) – Call matplotlib.pyplot.show() to display the plot.

  • save (str | Path | None, optional) – File path to save the figure at 300 DPI.

  • ax (matplotlib.axes.Axes | None, optional) – Matplotlib Axes to plot onto. If None, a new figure and axes are created.

Returns:

The Matplotlib Axes object used for plotting.

Return type:

Axes

Raises:

ValueError – If fc_vals or pvals are not 1D, contain non-numeric values, or have different lengths; if no valid data remains after filtering; if fc_thresh is not positive (when set); if pval_thresh is not in [0, 1] (when set); if top_labels is set but labels is None, or is not a positive integer; if highlight_labels is set but labels is None, contains duplicates, or contains non-string values; if both top_labels and highlight_labels are set; if labels contains non-string values; if ax is not a matplotlib.axes.Axes object (when set); if alt_color fails validation.

Examples

Basic usage with lists:

>>> from proteopy.utils.stat_tests import volcano_plot
>>> fc = [-2.1, -0.5, 0.3, 1.8, 3.0]
>>> pv = [0.001, 0.3, 0.5, 0.04, 0.0005]
>>> volcano_plot(fc, pv, show=False)
<Axes: ...>

With fold change and p-value thresholds:

>>> volcano_plot(
...     fc, pv,
...     fc_thresh=1.5,
...     pval_thresh=0.05,
...     show=False,
... )
<Axes: ...>

With top_labels to annotate the most significant hits:

>>> genes = ["GeneA", "GeneB", "GeneC", "GeneD", "GeneE"]
>>> volcano_plot(
...     fc, pv,
...     fc_thresh=1.5,
...     pval_thresh=0.05,
...     labels=genes,
...     top_labels=2,
...     show=False,
... )
<Axes: ...>

With highlight_labels to annotate specific proteins:

>>> volcano_plot(
...     fc, pv,
...     labels=genes,
...     highlight_labels=["GeneA", "GeneE"],
...     show=False,
... )
<Axes: ...>