/multipanel

name: multipanel
description: >
  Assemble multiple plots into ONE publication-ready multi-panel journal figure
  (e.g. Figure 1 with panels A, B, C). Use whenever the user asks to combine,
  compose, or lay out several plots as a single composite figure — newly plotted
  from data or from already-rendered panels the user supplies (PNG/PDF). Ask the
  user to pick one of two approaches: (1) redraw every
  panel into one unified figure using independent, tightly
  packed `subfigures` (each sized to its own labels, so axes need NOT align),
  consistent style, correctly placed panel letters, and per-panel legends/colorbars;
  (2) composite already-rendered PNG/PDF panels onto a mosaic canvas and add panel
  letters (image compositing, not plotting). Both export vector PDF + high-DPI PNG.
  For a SINGLE plot from a data table, use the sibling `omics-plotting` skill instead.
license: Proprietary (HITS Inc.)

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.

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: panelSelection
    kind: required
    source: user
    ask: "Which results earn a panel, and what claim should the assembled figure make?"
    default: null

  - id: D2
    param: panelOrder
    kind: required
    source: user
    depends_on: [D1]
    ask: "In what order should the panels be read, and which belong on the same row as a group?"
    default: "analysis order"

  - id: D3
    param: sharedScales
    kind: required
    source: user
    depends_on: [D1]
    ask: "Should panels that show the same quantity share one axis range, or each get its own?"
    default: "shared within a r