omics-plotting

--- name: omics-plotting description: > omics-plotting: publication-style figure authoring for omics / bioinformatics results with matplotlib / seaborn. Read this before writing any plotting or figure code in any omics analysis — RNA-seq, proteomics, single-cell, variant, or database results — not only when a plot is explicitly requested: whenever an analysis will produce a figure, load this first and follow its recipes. Covers volcano, MA, expression / correlation heatmap, GSEA bar / dot plot, box / violin / bar / ridgeline, PCA / UMAP / t-SNE scatter, Kaplan–Meier, Manhattan / QQ / forest. Supplies a shared journal-ready style and copy-paste recipes so every figure looks like one consistent system. To combine several plots into ONE multi-panel composite figure, use the sibling `multipanel` skill. license: Proprietary (HITS Inc.) ---

# omics-plotting

## Overview

When the user wants a figure, **generate it with matplotlib / seaborn**, applying the shared style block below. The user can hand-tune colors, fonts, or spines per plot, but unless they ask for something specific, paste the style block and reuse the palette so a whole analysis reads as one figure system at a glance.

This skill is self-contained: everything you need (style, palette, recipes) is in this document.

## When to use

- The user asks for a plot / figure / chart / visualization from a results table or an in-memory DataFrame (DEG table, enrichment result, expression matrix, long-form measurements, survival table…). - You are preparing figures for a report, a paper submission or presentation and want a consistent publication style.

> Combining several plots into one multi-panel composite, or assembling > user-supplied PNG/PDF panels, is handled by the sibling `multipanel` > skill — use this skill to draw each individual panel.

## Do NOT use for

- Interactive dashboards or web charts (this is static matplotlib output). - 3D molecular structure rendering (that is the structure viewer, not a plot).

## Key Concepts

### One consistent figure system

The core idea is that every figure from a single analysis should look like it came from the same publication. That is enforced by two shared objects: the `PUB_STYLE` rcParams block (fonts, spines, DPI, editable vector text) and a fixed `PALETTE` / directional color set (`UP`, `DOWN`, `NS`). Paste both at the top of every plot script and map the *same* group or direction to the *same* color across panels, so a reader can carry meaning from one figure to the next.

### Diverging vs sequential colormaps

Color encoding is not free choice. Use the **diverging** colormap (`DIVERGING_CMAP = "RdBu_r"`, always `center=0`, `vmin=-vmax`) for signed quantities where zero is meaningful — z-scores, log2 fold changes, correlations. Use the **sequential** colormap (`SEQUENTIAL_CMAP = "viridis"`) for unsigned magnitudes — densities, `-log10 p`, counts. Mixing these (a sequential map on signed data) hides the sign and misleads the reader.

### Data shape drives figure type

Each recipe expects a specific table shape: a per-gene DEG table (volcano, MA), a genes × samples matrix (heatmap), a samples × features matrix (PCA/UMAP), or long-form tidy rows (box/violin/bar, ridgeline, Kaplan–Meier). Identifying the shape first — then reading the header to confirm the real column names — is what selects the recipe. The column names in each recipe are defaults to override, not fixed requirements.

## Decision Framework

Pick the figure type from what the data represents and what question it answers:

``` What does the table hold? ├─ Per-gene stats (log2FC, padj) │ ├─ emphasize significance ......... Volcano │ └─ emphasize expression level ..... MA plot ├─ genes × samples matrix │ ├─ show patterns/clusters ......... Clustered expression heatmap (z-score) │ └─ show sample-sample QC .......... Correlation heatmap ├─ Enrichment / gene-set result │ ├─ signed effect (NES) ............ GSEA bar │ └─ ratio + size + significance .... GSEA dot plot ├─ Long-form measurements (x, y) │ ├─ compare distributions .......... Box / Violin │ ├─ compare means .................. Bar (with error bars) │ └─ many groups, shape matters ..... Ridgeline ├─ samples × features (high-dim) ...... PCA / UMAP / t-SNE └─ time-to-event + group ............. Kaplan–Meier ```

| Data you have | Question | Figure | Colormap / palette | |---|---|---|---| | DEG table | Which genes change, how significantly? | Volcano | `UP`/`DOWN`/`NS` | | DEG table | Effect vs abundance | MA plot | `UP`/`DOWN`/`NS` | | Expression matrix | Cluster structure | Clustered heatmap | diverging, center 0 | | Expression matrix | Sample QC | Correlation heatmap | diverging, [-1, 1] | | Enrichment result | Top pathways, direction | GSEA bar | `UP`/`DOWN` | | Enrichment result | Ratio + significance + size | GSEA dot plot | sequential | | Long-form | Group distributions | Box / Violin | categorical `PALETTE` | | High-dim matrix | Global sample layout | PCA / UMAP / t-SNE | categorical `PALETTE` | | Survival table | Group survival over time | Kaplan–Meier | categorical `PALETTE` |

## Workflow

1. **Identify the data source** — a workspace-relative CSV/TSV path or a DataFrame already in memory — and the **figure type** (pick from the table below). If the required columns are unclear, inspect the table's header first. 2. **Write one python script**: paste the style block, load the data, draw the plot with the matching recipe, and save to a **workspace-relative** path under `figures/`. 3. **Report the saved path** back to the user (and reference it in any report / deck by that relative path, e.g. ``).

## Shared style — paste at the top of every plot script

```python import matplotlib.pyplot as plt

# Publication style (colorblind-friendly, editable vector text, no top/right spines) PUB_STYLE = { "figure.dpi": 110, "savefig.dpi": 300, "savefig.bbox": "tight", "font.family": "sans-serif", "font.sans-serif": ["Arial", "Liberation Sans", "Nimbus Sans", "Helvetica", "DejaVu Sans"], "font.size": 11, "axes.titlesize": 13, "axes.titleweight": "bold", "figure.titlesize": 13, "figure.titleweight": "bold", "axes.labelsize": 12, "axes.linewidth": 1.0, "axes.spines.top": False, "axes.spines.right": False, "xtick.labelsize": 10, "ytick.labelsize": 10, "xtick.direction": "out", "ytick.direction": "out", "legend.frameon": False, "legend.fontsize": 9, "svg.fonttype": "none", "pdf.fonttype": 42, "ps.fonttype": 42, } plt.rcParams.update(PUB_STYLE) # or: with plt.rc_context(PUB_STYLE): ...

# Palette — reuse the SAME colors across every panel of an analysis UP, DOWN, NS = "#d73721", "#204897", "#d9d9d9" # up / down / not-significant PALETTE = ["#2a78d6", "#eb6834", "#1baf7a", "#eda100", "#e87ba4", "#008300", "#4a3aa7", "#e34948", "#12a4c0", "#a66a2e"] # categorical (CVD-safe order) GROUP_COLORS = {"Group1": "#204897", "Group2": "#e34948", "Group3": "#E7B800"} DIVERGING_CMAP = "RdBu_r" # z-score / log2FC heatmaps — set center=0, vmin=-vmax SEQUENTIAL_CMAP = "viridis" # magnitude / -log10 p / density ```

## Multi-panel / composite figures

For combining several plots into **one** multi-panel journal figure (panels A, B, C…), or assembling already-rendered PNG/PDF panels the user supplies, use the sibling **`multipanel`** skill — it owns the composition discipline (one `subplot_mosaic` canvas, per-panel legends, correctly placed panel letters, text-legibility rules, image assembly). Draw each panel with the single-panel recipes below, then compose per that skill. The recipes here each build their *own* figure, so do not call them directly for a composite — copy the recipe **body** onto a mosaic axis as `multipanel` describes.

## Plot catalogue

Pick the recipe by figure type. Columns listed are the **defaults** — override the column-name variables to match the actual table.

| Figure | Input shape | Key columns (defaults) | |---|---|---| | Volcano | DEG table | `log2FoldChange`, `padj`; optional label column | | MA plot | DEG table | `baseMean`, `log2FoldChange`, `padj` | | Expression heatmap | genes × samples matrix | numeric matrix, optional `index_col` | | Correlation heatmap | samples × features (numeric) | all numeric columns | | GSEA bar plot | enrichment result | `Term`, `NES`, `FDR q-val` | | GSEA dot plot | enrichment result | `Term`, `GeneRatio`, `Count`, `Adjusted P-value` | | Box / Violin / Bar | long-form | `x` (category), `y` (numeric), optional `hue` | | Ridgeline | long-form | numeric `x`, categorical `group` | | PCA / UMAP / t-SNE | samples × features | numeric features + optional `group` | | Kaplan–Meier | survival table | `time`, `event`, `group` | | Manhattan | GWAS summary stats | `CHR`, `BP`, `P` | | QQ plot | p-value vector | `P` | | Forest | effect + CI table | `label`, `estimate`, `ci_low`, `ci_high` |

## Recipes

Each is a full python script body. Adjust column names, thresholds, and the save path. All save under `figures/`.

**Volcano** (`-log10 p` vs `log2` fold change):

```python import numpy as np, pandas as pd df = pd.read_csv("deg_results.csv").dropna(subset=["log2FoldChange", "padj"]) fc, p = df["log2FoldChange"].to_numpy(float), df["padj"].to_numpy(float) nlp = -np.log10(np.clip(p, 1e-300, None)) fc_t, p_t = 0.58, 0.05 up, down = (fc >= fc_t) & (p < p_t), (fc <= -fc_t) & (p < p_t) ns = ~(up | down) fig, ax = plt.subplots(figsize=(7, 6)) ax.scatter(fc[ns], nlp[ns], c=NS, s=12, alpha=0.5, edgecolors="none", rasterized=True, label=f"NS ({ns.sum()})") ax.scatter(fc[down], nlp[down], c=DOWN, s=18, alpha=0.85, edgecolors="none", label=f"Down ({down.sum()})") ax.scatter(fc[up], nlp[up], c=UP, s=18, alpha=0.85, edgecolors="none", label=f"Up ({up.sum()})") for v in (fc_t, -fc_t): ax.axvline(v, ls="--", lw=0.8, color="0.5") ax.axhline(-np.log10(p_t), ls="--", lw=0.8, color="0.5") lab = (df["gene"] if "gene" in df else pd.Series(df.index)).astype(str).to_numpy() sig = np.where(up | down)[0] top = sig[np.argsort(nlp[sig])[::-1][:10]] # standalone: top ~10; composite panel: cut to <=5 try: # repel labels so they never overlap from adjustText import adjust_text texts = [ax.text(fc[i], nlp[i], lab[i], fontsize=7) for i in top] adjust_text(texts, ax=ax, expand=(1.3, 1.6), arrowprops=dict(arrowstyle="-", color="0.6", lw=0.5)) except ImportError: # no adjustText -> label fewer, with an offset for i in top[:5]: ax.annotate(lab[i], (fc[i], nlp[i]), xytext=(6, 6), textcoords="offset points", fontsize=7, ha="left", va="bottom") ax.set_xlabel(r"$\log_{2}$ fold change"); ax.set_ylabel(r"$-\log_{10}$ padj") ax.set_title("Volcano plot"); ax.legend(loc="upper right", markerscale=1.4) fig.tight_layout(); fig.savefig("figures/volcano.png") ```

**MA plot** (`log2` fold change vs mean expression; columns `baseMean`, `log2FoldChange`, optional `padj`):

```python import numpy as np, pandas as pd df = pd.read_csv("deg_results.csv").dropna(subset=["baseMean", "log2FoldChange"]) x = np.log10(df["baseMean"].to_numpy(float) + 1) fc = df["log2FoldChange"].to_numpy(float) sig = (df["padj"].to_numpy(float) < 0.05) if "padj" in df else np.zeros(len(df), bool) fig, ax = plt.subplots(figsize=(7, 5)) ax.scatter(x[~sig], fc[~sig], c=NS, s=10, alpha=0.5, edgecolors="none", rasterized=True, label="NS") ax.scatter(x[sig], fc[sig], c=UP, s=14, alpha=0.85, edgecolors="none", label=f"padj<0.05 ({int(sig.sum())})") ax.axhline(0, color="0.4", lw=0.8) ax.set_xlabel(r"$\log_{10}$(mean norm. count + 1)"); ax.set_ylabel(r"$\log_{2}$ fold change") ax.set_title("MA plot"); ax.legend(loc="upper right") fig.tight_layout(); fig.savefig("figures/ma.png") ```

**Clustered expression heatmap** (z-scored, seaborn `clustermap`):

```python import seaborn as sns, pandas as pd mat = pd.read_csv("expression.csv", ind