A reusable, publication-ready volcano plot utility for differential expression analysis.
This module is designed as a stable library function rather than an ad-hoc plotting script. It provides a single, explicit API that creates, annotates, lays out, saves, or displays volcano plots in one call, without exposing matplotlib internals.
- Single public API:
volcano(...) - One input file equals one subplot
- Automatic grid layout for multiple files
- Independent axes by default, optional shared axes
- CSV, TSV, and Excel input support
- Flexible gene or transcript annotation
- Publication-ready output formats (PNG, PDF, SVG)
- Explicit save vs display behavior
- Safe defaults suitable for teaching and large RNA-seq datasets
pip install biofxvolcano(
files,
log2fc_col="log2FoldChange",
pval_col="padj",
log2fc_cutoff=1.0,
fdr_cutoff=0.05,
share_axes=False,
panel_labels=True,
legend=True,
legend_loc="best",
xlabel="Log2 Fold Change",
ylabel="-Log10 p-value",
suptitle=None,
figsize=None,
outfile=None,
fmt="png",
dpi=300,
annotate=None,
)Input differential expression results.
Accepted types:
- string (single file)
- list of strings (multiple files)
Supported formats:
- .csv
- .tsv, .txt
- .xlsx, .xls
Behavior:
- One file produces one volcano plot
- Multiple files produce one subplot per file
- Layout is determined automatically
- File names (without extensions) are used as panel titles
Default: log2FoldChange
Name of the column containing log2 fold-change values.
Default: padj
Name of the column containing adjusted p-values (FDR).
Default: 1.0
Absolute log2 fold-change threshold used to classify significant points and_toggle vertical threshold lines.
Default: 0.05
Adjusted p-value threshold used to classify significance and draw the horizontal threshold line.
Default: False
If False, each subplot scales independently.
If True, all subplots share the same x and y limits.
Default: True
Draws panel labels (A, B, C, …) in the upper-left corner of each subplot.
Default: True
Controls whether a legend is drawn.
Default: best
Legend placement passed directly to matplotlib.
The legend is shown only on the first subplot.
Default: Log2 Fold Change
X-axis label applied to all panels.
Default: -Log10 p-value
Y-axis label applied to all panels.
Default: None
Optional figure-level title drawn above all panels.
Default: None
Figure size in inches as (width, height).
If None, the size is determined automatically based on the number of panels.
Default: None
Controls saving versus displaying the figure.
Behavior:
- If
outfileis None, the figure is displayed. - If
outfileis provided, the figure is saved and not displayed.
This avoids slow interactive rendering for large datasets.
Default: png
Output format used when saving the figure.
Supported formats:
- png
- svg
- jpg, jpeg
- tiff
If outfile already contains a file extension, that extension is used and fmt is ignored.
Default: 300
Dots per inch for raster formats (PNG, JPG, TIFF).
Ignored for vector formats such as PDF and SVG.
Default: None
User-defined gene or transcript annotations.
Accepted forms:
List of IDs: annotate = ["GENE1", "GENE2"]
Dictionary mapping ID to label: annotate = { "TRINITY_GG_1_c1033_g1_i10": "WRKY33", "TRINITY_GG_1_c1147_g1_i3": "PR1", }
Matching rules:
- IDs are matched against the DataFrame index if present
- Otherwise, the first column is used
- Missing IDs are silently ignored
- No assumptions are made about naming conventions
from biofx import volcano
volcano(
["DESeq2_J_vs_T_2023.csv", "DESeq2_J_vs_T_2024.csv"],
annotate={
"TRINITY_GG_1_c1033_g1_i10": "WRKY33",
"TRINITY_GG_1_c1147_g1_i3": "PR1",
},
suptitle="Differential expression across years",
outfile="volcano_years",
fmt="pdf",
)MIT License