multipanel

# multipanel

## Overview

A multi-panel figure is **one** figure, built one of two ways depending on what
you have:

- **Option 1 — redraw every panel** (you have the data or plotting code): draw
  each data panel with a python script into its **own `subfigure`** so it packs
  to its own labels — no empty bands, and axes need NOT align across the grid.
  Follow the discipline below so legends stay inside their panels, panel letters
  sit at each panel's own top-left, and text never overlaps.
- **Option 2 — composite finished images** (you only have rendered PNG/PDF panels):
  paste them onto a `plt.subplot_mosaic` canvas — fine here, since images carry no
  tick labels to misalign — add panel letters, and export.

A mix is allowed: if one or two panels are image-only (no data/code), `imshow`
them onto their own subfigure axes and redraw the rest into the same figure. Both
modes export a vector PDF and a high-DPI PNG.

**Always export the individual panels AND the composite.** Every run outputs both:
one standalone figure per panel (`figure1A.png`, `figure1B.png`, …) and the combined
figure (`combined_figure1.pdf` + `.png`) — not just the composite. Because a
matplotlib `subfigure` cannot be saved on its own, factor every data panel's plotting
body into a `draw_<letter>(ax)` function (option 1); the same function then draws onto
the composite's subfigure axis AND onto a fresh standalone figure, so the panels stay
identical across both outputs with no duplicated drawing code. See "Exporting
individual panels" below.

This skill covers **composition**. For how to draw each individual plot type
(volcano, GSEA bar, heatmap, box/violin, PCA, Kaplan–Meier, …), use the sibling
`omics-plotting` skill — copy each recipe's **body** onto a subfigure's axis rather than
calling it as a standalone figure. Everything you need here (shared style,
composite recipe, panel-label helper) is in this document.

## When to use

- The user asks for a **multi-panel / composite / journal figure** (panels A, B,
  C…) combining two or more plots into one page of image.
- The user hands you or points out **already-rendered panels (PNG/PDF)** and wants them combined
  into one figure (image assembly — see "Assembling user-provided panels").
- You are assembling a figure for a report, a paper submission, or a presentation
  and want all panels to read as one consistent system.

## Do NOT use for

- A **single** plot from a data table — use the sibling `omics-plotting` skill.
- Interactive dashboards or web charts (this is static matplotlib output).
- 3D molecular structure rendering (that is the structure viewer, not a plot).

## Key Concepts

### Redraw vs composite — two composition modes

There are two fundamentally different ways to build a composite, and the user
chooses. **Redraw (option 1)** rebuilds every panel from data or
code in one script, giving uniform style, fonts, colors, and panel letters — best
when you hold the underlying data/DataFrame or the plotting code. **Composite
(option 2)** pastes already-rendered PNG/PDF panels onto a canvas and only adds
panel letters — image assembly, not plotting — best when you have only the
finished images. A mix is allowed: image-only panels are `imshow`-pasted while
data panels are redrawn, all into one figure.

### Independent subfigures vs shared mosaic

The central layout decision. Giving **each panel its own `subfigure`** lets it run
its own `constrained_layout` and pack tightly to its OWN labels — panels sit flush
with no empty bands, and axes deliberately do NOT align across the grid. A single
shared `subplot_mosaic` gridspec instead equalizes every column's margin to its
widest y-label, leaving wide empty bands beside short-label panels. Independent
subfigures are the default here because composites usually mix heterogeneous plot
types; a shared mosaic is correct only when panels genuinely share a scale and are
meant to be read against each other.

### Panel letters in the subfigure frame

Panel letters (bold `A, B, C…`) must sit at each panel's OWN outer top-left, left
of that panel's y-axis labels — never merged into the title and never snapped to a
shared column x-position. Placing each letter at `(0, 1)` in its subfigure's
coordinate frame (`transform=sf.transSubfigure`) guarantees it hugs its panel
regardless of neighbors' label widths.

## Decision Framework

Start from what you have, then how panels relate:

```
What sources do you have?
├─ Data / code for every panel .................. Option 1: redraw all
├─ Only finished PNG/PDF images ................. Option 2: composite images
└─ Mix (some data, some image-only) ............. Option 1 + imshow the image-only panels
        │
        ▼
How do the panels relate?
├─ Heterogeneous plot types (default) ........... Independent subfigures (tight pack, axes need NOT align)
└─ Same scale, read against each other .......... Shared subplot_mosaic (aligned axes)
        │
        ▼
Layout: sketch the grid [[...]], nest subfigures for spanning panels, fill every cell
```

| Situation | Approach | Layout primitive | Panel letters |
|---|---|---|---|
| Have data/code for all panels | Redraw (option 1) | `fig.subfigures(...)` per panel | subfigure frame `(0,1)` |
| Only rendered images | Composite (option 2) | `plt.subplot_mosaic` + `imshow` | mosaic axes top-left |
| Some data, some image-only | Redraw + paste | subfigures + `imshow` leaf | subfigure frame `(0,1)` |
| Panels share a common scale | Shared mosaic | `subplot_mosaic` aligned | axes top-left |
| Spanning panel (e.g. bottom row) | Nested subfigures | `top[0].subfigures(1, 2)` | leaf subfigure frame |

## Workflow

1. **Ask which approach first — ask the user, then wait.** Both approaches
   below are usually viable and the choice is the user's, so **before drawing or writing any
   script, ask the user to choose between these two concrete options**:
   - **Option 1 — Redraw every panel into one unified figure** (from data/code): consistent
     styl