Make Figures

Make-Figures Skill

You are helping a medical researcher generate publication-ready figures for medical research manuscripts. Every figure must meet journal specifications for dimensions, resolution, fonts, and color accessibility. Produce clean, data-focused visuals with no chartjunk.

Credits

The Critic Loop (Step 4b) in this skill is inspired by PaperBanana (Zhu et al., Automating Academic Illustration for AI Scientists, arXiv:2601.23265, 2025) and by prior self-refinement research — Self-Refine (Madaan et al., 2023), Reflexion (Shinn et al., 2023), and Constitutional AI (Anthropic, 2022). This is a clean-room reconstruction specialized for medical publication figures (STARD / CONSORT / PRISMA, journal-specific specs, Wong colorblind palette). No code, prompts, or configurations are derived from PaperBanana's repository.

Communication Rules

• Communicate with the user in their preferred language.
• All figure text (labels, legends, annotations) must be in English.
• Medical terminology is always in English.

Data Privacy Check

Before reading any data file, check whether it might contain Protected Health Information (PHI):

1. If *_deidentified.* files exist in the working directory, use those preferentially. 2. If only raw CSV/Excel files exist (no *_deidentified.* counterpart), warn the user (ask in the user's preferred language):

"Does this data contain patient identifiers (names, national ID / RRN, contact details, etc.)?

If so, please de-identify it first with the /deidentify skill."

3. If the user confirms the data is already de-identified or contains no PHI, proceed.

Reference Files

• Figure specifications: ${CLAUDE_SKILL_DIR}/references/figure_specs.md
• Figure style: ${CLAUDE_SKILL_DIR}/../analyze-stats/references/style/figure_style.mplstyle (or project's CLAUDE.md if available)
• Project data: See CLAUDE.md for data locations under 2_Data/

Read figure_specs.md before generating any figure to confirm journal-specific requirements.

---

Journal AI-Image Policies (CRITICAL — check BEFORE generation)

Synced with the user's global rule ~/.claude/rules/journal-ai-image-policies.md. The table below is the local copy used during autonomous workflow; the global rule is authoritative when conflicts arise.

Hard rule: For JACC, NEJM, or any "unknown" target journal, never use Gemini / DALL-E / Midjourney / Stable Diffusion / Nano Banana to create images that will appear in figures, Central Illustrations, or graphical abstracts. AI text-editing of the manuscript prose remains acceptable subject to standard disclosure.

Default workflow when AI images are not allowed

1. SMART Servier Medical Art — https://smart.servier.com/, CC BY 4.0, free, 3,000+ vector medical icons (anatomy, organs, ethnicity-specific human figures, drugs, devices). Commercial / journal use allowed. Required attribution (1 line in figure legend OR methods):

Anatomical icons modified from SMART Servier Medical Art (CC BY 4.0).

2. NIAID BioArt (https://bioart.niaid.nih.gov) — public domain (US Govt), microbiology / immunology / lab-tech focus. 3. BioRender (https://www.biorender.com) — institutional license usually required; use the exported "Publication-ready" PNG/TIFF and cite per BioRender publication policy. 4. For "diseased" variants not directly available (e.g., calcified vessel from a clean vessel): reuse the healthy asset and overlay disease markers via matplotlib scatter / Circle / PathPatch. Keeps the entire pipeline non-AI and reproducible.

Asset directory convention

manuscript/figures/_assets_servier/      # CC BY 4.0 source PNGs
manuscript/figures/_assets_servier/CITATION.md   # source URL + download date per asset
manuscript/figures/_assets_data/         # data-driven raster (R / matplotlib heat maps, KM, etc.)
manuscript/figures/_legacy/              # archived prior versions

Composition scripts should load only from _assets_servier/ and _assets_data/. If a script imports from _assets_ai/, treat it as a policy violation for JACC/NEJM/unknown targets.

When a figure is produced by a data-driven .py/.R script (ROC, forest, KM, calibration, heat maps), lint that script before finalizing with the /analyze-stats code-quality gate (check_generated_code.py {script} --strict): it catches a missing plotting seed for any bootstrapped CI band, a hardcoded absolute data path, or a hand-typed data literal that should have been read from the analysis CSV.

Decoration vs information

Even when AI images are allowed, AI-generated illustrations are immediately recognizable to experienced reviewers (small decorative icons that add no information, overly uniform layouts, generic clip-art style). For high-impact submissions, prefer Servier / BioArt / BioRender + matplotlib overlays over AI.

---

DPI and Resolution Guide

Practical workflow for screen captures:

• Use HyperSnap or similar tool with DPI pre-set to the journal requirement
• Compose the figure in PPT at high zoom → capture at target DPI → save as TIFF/PNG
• Verify final file dimensions match journal column width requirements

---

Visual Abstract / Graphical Abstract

Many journals now require or strongly encourage visual abstracts. European Radiology made graphical abstracts mandatory for all Original Articles from first revision (Jan 2025). Submitting one voluntarily signals effort and can improve editorial impression.

Journal Requirements

Check the target journal profile (write-paper/references/journal_profiles/) for specific visual abstract requirements before starting.

Workflow

1. Check journal template. Look for an official PPTX template in ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/{journal}.pptx. If no journal-specific template exists, use medsci_default.pptx. 2. Extract content from the manuscript:

• Title: Full article title
• Hypothesis/Question: Derived from Key Point 1 or study objective (max 1 sentence)
• Methodology: Brief flowchart or ≤3 bullets, <6 words each
• Visual element: Study's own figure (ROC curve, flow diagram, representative image)
• Badges: Patient cohort (N=...) | Modality/organ | Single/Multi-center
• Main finding: Derived from Key Point 3 (<20 words)
• Citation: Journal (year) Authors; DOI

3. Select visual element (priority order — no API needed for top options): 1. Study's own figures (ROC, flow diagram, representative image) — always preferred 2. Free illustration from Servier Medical Art or NIAID BioArt (see ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md) 3. Manual drawing in PPT/Keynote/Figma 4. AI generation via generate_image.py --style medical (only if GEMINI_API_KEY set) 4. Generate using the script:

   python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
     --template european_radiology \
     --title "Article Title" \
     --hypothesis "Research question" \
     --methods "Method 1|Method 2|Method 3" \
     --finding "Main finding statement" \
     --citation "Eur Radiol (2026) Author A et al; DOI:..." \
     --visual figures/fig1_roc_curve.png \
     --badges "N=450|CT chest|Multi-center" \
     --output figures/visual_abstract.pptx

5. Review with user. Open the PPTX to verify layout and content. Iterate. 6. Export. PPTX is the primary deliverable. For PNG: open in PowerPoint/Keynote → export, or use LibreOffice CLI (soffice --headless --convert-to png).

Design Principles

• One page, landscape (16:9) or per journal template specification
• Three sections: Study question → Key method → Main result
• Use the study's actual figures rather than generic graphics
• Minimize text — let visuals carry the message
• Every visual element must serve a purpose (no decorative clip-art)

Available Templates

To add a new journal template: see ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/template_guide.md.

---

Central Illustration vs Visual Abstract

A Central Illustration (CI) is not a Visual Abstract (VA). They serve different purposes and follow different rules. JACC family journals (JACC, JACC: Asia, JACC: Cardiovascular Imaging, JACC: Heart Failure, JACC: CardioOncology, JACC: Clinical Electrophysiology, JACC: Basic to Translational Science) require a Central Illustration with every Original Article. Reference: Fuster V, Mann DL. JACC. 2019;74(22):2816–2820.

Fuster-Mann five rules (CI must pass all)

1. Know the message. One finding, not study design + multiple findings. 2. Convey graphically, not textually. Even a simple KM curve is OK. 3. Avoid using too much text. Replace with icons or arrows. 4. Avoid secondary messages. ≤ 5 seconds for a viewer to state the main finding. 5. Simplicity is superior. Default to fewer panels.

Full guidance and validation thresholds: ${CLAUDE_SKILL_DIR}/references/jacc_central_illustration_principles.md.

CI mode invocation

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --type central-illustration \
  --visual figures/central_illustration_v2.png \
  --citation "FirstAuthor Last et al. Journal Name 2026; vol(issue):pages." \
  --output submission/jacc_asia/central_illustration.pptx \
  --ci-zones 3 --ci-label-words 22 --ci-numerical-points 2 \
  --ci-raw-text "warranty drops to 3 years in age 45+ with cardiometabolic burden; MASLD HR 1.77"

CI mode validates before rendering and rejects (exit 2) if any of: zones > 3, label words > 30, numerical points > 4, or methodology terms (cohort flow / inclusion / exclusion / study design / enrollment / randomized / sample size / CONSORT / PRISMA / STARD) appear in --ci-raw-text. Override individual rules with --ci-allow {zones|words|numerical|methods} only when you have a defensible reason.

The JACC submission PPTX is a 10×7.5 in slide with 4 placeholders (citation textbox, content picture, footer textbox reserved, JACC logo). The red border + blue "CENTRAL ILLUSTRATION:" header are applied by JACC editorial after acceptance — authors submit only the content figure + citation.

---

Workflow

Step 1: Specify

Before specifying figure type, read `${CLAUDE_SKILL_DIR}/references/design_principles.md` — identify (1) the one-sentence key message, (2) audience and reading-time budget, and (3) whether a figure is the right vehicle (vs a small table or in-line text). The five strategies in that file shift Step 1 from "which chart fits the data" to "what should the reader remember 10 seconds later." Skip only when the figure is mandated by a reporting guideline (e.g., PRISMA / CONSORT flow), and even then apply the cognitive-load checklist.

For reporting-guideline figures, also load ${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md — the 14-row table tells you which guideline mandates which figures and whether this skill ships an official template (✅), generic flow only (⚠️), or needs manual production (❌). Critical for AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI, CLAIM 2024, DECIDE-AI).

For medical AI / engineering pipeline figures (DICOM workflow, annotation pipeline, federated learning topology, model architecture), also load ${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md — canonical layouts, required annotations, and tool selection per type.

Optional flags:

• --study-type <type>: One of: diagnostic-accuracy, ai-validation, meta-analysis, dta-meta-analysis, observational-cohort, rct, case-report. When set, auto-generate the full figure set from the Study-Type Figure Sets table below without prompting for individual figure types.
• --data-dir <path>: Directory containing analysis outputs (CSVs, _analysis_outputs.md). Default: current working directory.

Ask the user for: 1. Figure type (from the supported types below) — skipped when --study-type is provided 2. Data source (file path, DataFrame, or manual values) 3. Target journal (for dimension/font requirements) 4. Panel layout (single panel, multi-panel, or let you decide) 5. Any special requests (annotations, highlights, reference lines) 6. Study type (if not passed via --study-type): determines the required figure set

If the user provides enough context, infer missing parameters and confirm before proceeding.

Step 2: Configure

1. Load the figure style file:

   import matplotlib.pyplot as plt
   import os
   style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')
   if os.path.exists(style_path):
       plt.style.use(style_path)

2. Look up journal-specific dimensions from ${CLAUDE_SKILL_DIR}/references/figure_specs.md. 3. Set the colorblind-safe palette (Wong palette by default). 4. Configure font sizes per element type (title, axis label, tick label, legend, annotation).

Step 3: Generate

Create the figure using Python (matplotlib/seaborn as primary, with specialized libraries as needed).

Script structure:

"""
Figure: {description}
Date: {YYYY-MM-DD}
Target: {journal}
Dimensions: {width} x {height} inches @ {DPI} DPI
"""
import numpy as np
import matplotlib.pyplot as plt
import os

style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')
if os.path.exists(style_path):
    plt.style.use(style_path)

# Wong colorblind-safe palette
WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']

np.random.seed(42)

Step 4: Review

Present the figure to the user and ask:

• Does the layout work?
• Are labels and annotations correct?
• Any adjustments to colors, sizing, or emphasis?

Iterate until the user approves.

Step 4b: Critic Loop (self-critique before final export)

Before Step 5 Export, run the automated Critic Loop. This is two stages — deterministic quantitative checks via Python, then qualitative review by Claude itself — and the combined output tells us whether to re-render or hand off to the user.

Stage 1: Quantitative checks (`critic_figure.py`)

python ${CLAUDE_SKILL_DIR}/scripts/critic_figure.py \
    figures/fig1_stard.png \
    --type stard \
    --spec-min-dpi 600 \
    --spec-width-in 7.0 \
    --source-text figures/fig1_stard.txt \   # optional: expected strings for OCR coverage
    --out figures/fig1_stard.critique.json

This produces a JSON report covering:

• DPI and physical width vs. journal spec
• Dominant-color breakdown and out-of-Wong-palette fraction
• OCR-detected word count, minimum text height, and (if a source-text file

was provided) source-word coverage

Stage 2: Qualitative review (Claude session)

1. Use the Read tool to load the generated PNG. 2. Read the corresponding rubric file:

• Flow diagrams: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/flow_diagram.md

(sections A–G; section G adds cognitive-load and template-fidelity checks)

• Data plots: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/data_plot.md

(sections A–G; section G adds calibration / fairness / colorblind+redundant / dataset-flow / decision-curve checks for medical AI papers)

• For PRISMA / CONSORT / STARD / STROBE specifically, also read

${CLAUDE_SKILL_DIR}/references/flow_diagram_lessons.md — five production lessons covering official-template fidelity, PDF export fidelity (VML fallback), docx XML escape, sequential placeholder mapping, and frozen-version sync with the manuscript.

• For AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI,

CLAIM 2024, DECIDE-AI), also read ${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md — the row for the target guideline lists mandatory figures and which ones this skill cannot template (production path documented per row).

• For medical-AI pipeline / DICOM / federated / architecture figures,

also read ${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md. 3. If exemplars exist in ${CLAUDE_SKILL_DIR}/references/exemplar_diagrams/{type}/, Read 1–3 of them plus their _why.md notes. For a non-flow data plot (forest, ROC, KM, calibration), read the matching anatomy model in ${CLAUDE_SKILL_DIR}/references/exemplar_plots/ (e.g., forest_plot.md). 4. Score every rubric item as PASS / PARTIAL / FAIL with a one-line note, using the format at the bottom of the rubric file. 5. Emit a "Required edits before next render" list of concrete source-code changes (D2 node renames, count corrections, matplotlib parameter tweaks).

Refinement loop

• If all items are PASS → proceed to Step 5 Export with critic_pass: yes.
• If any item is FAIL → apply the required edits to the source (D2 file or

matplotlib script), re-render, and re-run Stage 1 + Stage 2. Default maximum is T=2 rounds; the user may request up to T=3.

• If after the max rounds some items remain PARTIAL, proceed with

critic_pass: partial and record the residual items in the manifest's critic_notes field.

Record the final state in _figure_manifest.md (see the manifest format below) so downstream steps (/write-paper Phase 2 embedding and Phase 7 DOCX build) and future critic passes can see the history.

Step 5: Export

Save final outputs:

• PDF (vector format, preferred for journal submission)
• PNG (300 DPI raster, for review and presentation)
• TIFF (if the journal requires it, 300 DPI LZW compression)

Name files descriptively: fig1_roc_curve.pdf, fig2_consort_flow.pdf, etc.

For PPTX outputs (visual abstract, central illustration, or any deck the figure will live in): run the Mac-compatibility validator before delivery. PowerPoint Mac silently drops TIFF, renders <a:sp3d> 3-D bevels as red outlines that PDF export does not show, and refuses to open files whose app.xml slide count disagrees with the actual slide XML files. This script catches all four classes of defect codified in ~/.claude/rules/pptx-mac-compatibility.md:

python ${CLAUDE_SKILL_DIR}/scripts/validate_pptx_mac_compat.py \
    figures/visual_abstract.pptx \
    --json figures/visual_abstract.mac_compat.json \
    --strict

Exit code 1 means at least one FAIL — fix per the fix: field in the JSON report and re-render the PPTX before delivery. Exit code 0 with WARN is acceptable. Skip this step when the figure is PNG/PDF only (no PPTX).

Step 6: Design QC Checklist

Before delivering the final figure, verify all items:

• [ ] Font: Sans-serif (Arial/Helvetica), minimum 7pt, axis labels ≥ 9pt
• [ ] Color: Wong/Okabe-Ito colorblind-safe palette used
• [ ] Colorblind test: Would the figure work for deuteranopia? (no red-green only distinctions)
• [ ] Grayscale test: Information preserved when printed in black & white
• [ ] Alignment: All elements on a consistent grid; panels aligned
• [ ] Vector output: PDF/SVG saved (not just PNG)
• [ ] Resolution: ≥ 300 DPI for raster elements, ≥ 600 DPI for line art
• [ ] Journal specs: Dimensions, font, and format match target journal requirements
• [ ] No chartjunk: No 3D effects, unnecessary gridlines, gradient fills, or decorative elements
• [ ] Caption: Drafted with key finding, abbreviations, statistical details, and sample size

---

Study-Type Figure Sets

When the study type is known (from /write-paper Phase 0 or user specification), auto-detect and generate the complete required figure set without asking for each figure individually.

After generating all figures, create a structured manifest file at figures/_figure_manifest.md:

# Figure Manifest
Generated: {YYYY-MM-DD}
Study type: {study type or "custom"}

| Figure | Path | Type | Tool | Critic | Rounds | Description |
|--------|------|------|------|--------|--------|-------------|
| Figure 1 | figures/fig1_stard_flow.svg | flow-diagram | D2 | yes | 2 | STARD participant flow diagram |
| Figure 2 | figures/fig2_roc.pdf | roc-curve | matplotlib | yes | 1 | ROC curves for Model A vs B |
| Figure 3 | figures/fig3_calibration.pdf | calibration | matplotlib | partial | 3 | Calibration plot; legend still crowded (see notes) |

## Critic notes
- Figure 3: after 3 rounds, legend placement remains crowded at the
  double-column width. Candidate remediations documented but not applied
  to avoid reducing data-point visibility.

Manifest field definitions:

• Path: Relative path from project root
• Type: One of: flow-diagram, roc-curve, forest-plot, funnel-plot, calibration, km-curve, bland-altman, confusion-matrix, box-violin, bar-chart, heatmap, pipeline, visual-abstract, sroc-curve, other
• Tool: Tool used to generate (matplotlib, D2, python-pptx, seaborn, etc.)
• Critic: yes (all rubric items PASS) / partial (some PARTIAL after max rounds) / no (never critiqued — avoid for submission figures) / skip (deliberately bypassed, e.g., panel figure assembled externally)
• Rounds: Number of Critic Loop rounds executed (0 if skipped)
• Description: One-line description suitable for figure legend context

A ## Critic notes section at the bottom of the manifest records any residual PARTIAL items and the rationale for accepting them.

This manifest is consumed by /write-paper Phase 2 (figure embedding) and Phase 7 (DOCX build). It MUST exist after figure generation completes. Verify the file is non-empty before finishing.

Flow diagram generation rule: STARD/CONSORT/PRISMA/STROBE flow diagrams MUST use the standardized R pipeline scripts/generate_flow_diagram.R (DiagrammeR + Graphviz dot + rsvg). This is the single canonical tool for all four reporting-guideline flow diagrams. Do NOT use matplotlib FancyBboxPatch (manual coordinates break when text changes, and patches distort when embedded in DOCX). Do NOT use D2 for new flow diagrams (font control is weak, overlap requires manual post-processing). The legacy D2 recipe remains documented below as a fallback only when R is unavailable.

R flow diagram recipe (mandatory for all flow diagrams):

The pipeline reads a YAML config describing nodes/edges and produces: a true vector PDF (journal submission), a 300 dpi PNG (review copy), and a 600 dpi PNG (RSNA/Eur Radiol line-art). Default style is single-color black outline with white fill in Arial, overriding D2's colored defaults and matplotlib's manual coordinates.

# 1. One-time system dependency:
brew install librsvg
Rscript -e 'install.packages(c("DiagrammeR","DiagrammeRsvg","rsvg","yaml"))'

# 2. Author a YAML config. Templates for each type live at
#    references/exemplar_diagrams/{strobe,consort,prisma,stard}/template_input.yaml
# 3. Render:
Rscript ${CLAUDE_SKILL_DIR}/scripts/generate_flow_diagram.R \
    --type   {strobe|consort|prisma|stard} \
    --config path/to/counts.yaml \
    --out    figures/figure1_flow
# Outputs: figure1_flow.pdf, figure1_flow.png (300 dpi), figure1_flow_600.png

YAML schema highlights:

• rankdir: TB (top-down, default) or LR (left-to-right).
• nodes: list with id, label (use literal \n for line breaks, real Unicode –, ≤, −, •).
• Optional per-node: highlight: true (thicker border), shape: note (side boxes), rank_same_with: <other_id> (place on same horizontal rank).
• edges: list with from, to, optional style: dashed, arrow: false (no arrowhead), constraint: false (edge ignored by layout engine — use for exclusion side-links).
• Numbers in labels MUST be CSV-derived in an upstream R script that emits the YAML, or hand-written only when the value lives in a commit-tracked data artifact. Follow numerical-safety rules.

Style is fixed (do not override in the YAML):

• Monochrome: all boxes color=black, fillcolor=white, fontname="Arial".
• Penwidth 1.2 default, 1.8 for highlighted cohort box.
• Arrow style: black solid, arrowsize 0.75. Dashed without arrowhead for exclusion side-links.
• Bullet alignment in multi-item labels: Graphviz \l (left-align), never \n (center). Each \l applies to text preceding it.
• No HTML-like labels (label=<...> with <B>, <I>, •). Plain quoted labels with \l bullets produce tighter, more readable structure than HTML ragged wrapping. Do not reintroduce without explicit approval.
• To add one emphasis color (e.g., Wong blue #0072B2 for a single highlighted box), edit scripts/generate_flow_diagram.R — do not inline hex colors in YAML.

Per-project `create_figure1.R` pattern (preferred for complex flows):

When the flow has derived counts, stopifnot() reconciliation, multi-rank {rank=same; ... } constraints, or exclusion side-cars that the generic YAML dispatcher cannot express cleanly, write a per-project create_figure1.R directly (same DiagrammeR + DiagrammeRsvg + rsvg stack, sprintf'd dot string). This is the dominant pattern when the generic YAML dispatcher cannot capture the flow:

• STROBE cohort: <project>/manuscript/figures/create_figure1.R
• STARD: <project>/Analysis/figures/create_figure1.R or <project>/figures/v2_monochrome/create_figure1.R
• PRISMA / PRISMA-DTA: <project>/5_Figures/create_figure1.R or <project>/analysis/create_figure1.R
• CONSORT-edu (naturalistic allocation): <project>/figures/v2_monochrome/create_figure1.R

Copy the STYLE_HEADER (graph/node/edge attrs) verbatim from any exemplar; then customise nodes, edges, and {rank=same} blocks. Use read.csv() for cohort counts when possible; if hardcoded, every number must have a source comment referencing manuscript line / CSV cell / screening log row.

Legacy D2 fallback (only when R unavailable):

d2 --layout elk --theme 0 --pad 20 flow.d2 /tmp/raw.png --scale 2
# Resize + 85% vertical compression via Pillow; then render PDF:
d2 --layout elk --theme 0 --pad 20 flow.d2 figures/fig1_flow.pdf

Use font-size: 20-24, stroke: black, fill: white. D2 PDF is vector; D2 PNG needs the resize step to match publication density.

---

Tool Selection Guide

Choose the right tool for each figure type. Using matplotlib for flow diagrams leads to hard-coded coordinates that break when text changes — use auto-layout tools instead.

Data Visualization → matplotlib/seaborn (this skill)

Best for figures where data drives the layout. This skill handles these directly:

Flow Diagrams → Dedicated Tools (NOT matplotlib)

Flow diagrams require auto-layout engines. Do NOT use matplotlib patches with manual coordinates — this causes the "absolute coordinate hell" problem where changing one box breaks all downstream positions.

R workflow for flow diagrams: See the "R flow diagram recipe" above in the Flow diagram generation rule. Key points: YAML config → Rscript scripts/generate_flow_diagram.R --type <t> --config <yaml> --out <prefix> → PDF + 300/600 dpi PNG. Templates in references/exemplar_diagrams/{strobe,consort,prisma,stard}/template_input.yaml.

Official Reporting Guideline Templates → templates/official/

When a journal requires the canonical, statement-issued template (rather than the auto-laid-out R version), use the bundled official files in templates/official/{prisma2020,consort2010,stard2015,spirit2013}/.

Refresh / fill workflow:

# Refresh from canonical sources (CC-BY 4.0 / public-statement licenses)
bash ${CLAUDE_SKILL_DIR}/scripts/fetch_official_templates.sh

# Build PRISMA 2020 .pptx (one-time; site blocks programmatic .docx fetch)
python3 ${CLAUDE_SKILL_DIR}/scripts/build_prisma2020_template.py \
    --variant new \
    --out ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx

# Fill counts — positional 10-tuple matching most SR/MA workflows:
#   n_db, n_dup, n_screened, n_screen_excluded,
#   n_sought, n_assessed, n_excl_r1, n_excl_r2, n_excl_r3, n_studies
python3 ${CLAUDE_SKILL_DIR}/scripts/fill_prisma_template.py \
    --template ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
    --counts "315,122,186,7,111,204,102,84,3,15" \
    --out fig1_prisma_filled.pptx

# Or use full JSON mapping for studies with non-standard PRISMA splits
python3 ${CLAUDE_SKILL_DIR}/scripts/fill_prisma_template.py \
    --template ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
    --counts-file my_counts.json \
    --out fig1_prisma_filled.pptx

# STROBE — parametric single-script builder (cohort study; spine structure varies per study).
# YAML schema: stages, spine (id/stage/text), exclusions (after/text). Consecutive same-stage
# rows share one phase label automatically. Stage box fills auto-pick readable text color.
python3 ${CLAUDE_SKILL_DIR}/scripts/build_strobe_template.py \
    --config figures/figure1_strobe.yaml \
    --out    figures/figure1_strobe.pptx

For STROBE the canonical KJR/Radiology/BMJ submission flow is:

1. Render the vector submission file via the auto-fitting Graphviz path: Rscript ${CLAUDE_SKILL_DIR}/scripts/generate_flow_diagram.R --type strobe --config figures/figure1_strobe_graphviz.yaml --out figures/figure1 2. Build the editable PowerPoint companion via build_strobe_template.py so co-authors and senior reviewers can adjust prose/positioning before sign-off. 3. Re-export the final PPTX to PDF/TIFF only after co-author edits are integrated.

See templates/official/NOTES.md for licenses, attribution, and refresh notes.

Visual / Graphical Abstracts → python-pptx Template Generator

See the Visual Abstract section above for the full workflow.

Hybrid Workflow (recommended for publication)

Data plots:    matplotlib/seaborn → PDF + PNG (this skill)
Flow diagrams: generate_flow_diagram.R (DiagrammeR + rsvg) → PDF + 300/600 dpi PNG
Final assembly: pandoc or python-docx (auto-embedded in DOCX)

---

Supported Figure Types (matplotlib/seaborn)

---

Figure Type Templates

ROC Curve

from sklearn.metrics import roc_curve, auc

fig, ax = plt.subplots(figsize=(3.5, 3.5))
fpr, tpr, _ = roc_curve(y_true, y_score)
roc_auc = auc(fpr, tpr)
ax.plot(fpr, tpr, color=WONG[5], lw=1.5,
        label=f'Model (AUC = {roc_auc:.3f})')
ax.plot([0, 1], [0, 1], 'k--', lw=0.8, alpha=0.5)
ax.set(xlabel='1 - Specificity', ylabel='Sensitivity',
       xlim=[-0.02, 1.02], ylim=[-0.02, 1.02])
ax.legend(loc='lower right', frameon=False)

• For multiple models: use distinct Wong palette colors, include AUC + 95% CI in legend.
• For comparison: report DeLong p-value in annotation.

Forest Plot

• Horizontal layout: effect sizes as squares (sized by weight), CIs as lines.
• Diamond at bottom for pooled estimate.
• Vertical dashed line at null effect (OR=1 or MD=0).
• Axis label: "Favours A | Favours B" or appropriate.
• Include heterogeneity stats (I-squared, p) below the diamond.

Flow Diagrams (STROBE / CONSORT / PRISMA / STARD)

Single canonical tool: `scripts/generate_flow_diagram.R` (see the R flow diagram recipe above). Do not fall back to matplotlib for flow diagrams — manual coordinates break when text changes and patches distort in DOCX. D2 remains a documented legacy fallback only when R is unavailable.

Layout invariants:

• Rectangular boxes with rounded corners for stages; notes (shape: note) for exclusion side-boxes.
• Vertical top-down flow by default; horizontal only when the manuscript layout demands it.
• Every box label contains the count (e.g., "Assessed for eligibility\n(n = 450)").
• Numbers are CSV-derived (numerical-safety) — author the YAML from an R/Python script that reads the upstream data, or cite the source file in a comment when a literal value is unavoidable.
• Follow the official template layout from each guideline.
• Use relative positioning — never hard-code absolute y-coordinates. Calculate each box

position from the previous box's bottom edge plus a consistent gap constant.

• Define gap constants at the top of the script (e.g., GAP_SMALL = 1.5, GAP_BRANCH = 2.2).
• Avoid magic number padding in arrow endpoints — use named constants.

D2 approach (recommended):

d2 --layout elk --theme 0 flow.d2 output.svg
# Then: open SVG in Figma → grid-snap → font swap → export PDF

Caption ↔ flow-SSOT reconciliation (before Step 5 Export). The flow-diagram config (the YAML/script that generate_flow_diagram.R consumes) is the single source of truth for participant counts. A hand-written Figure 1 caption drifts from it whenever the cohort is re-locked but the caption is not — the classic "caption says n = 1,284 analytic, diagram box says n = 998" defect, which surfaces only at submission. Re-derive the caption counts from the flow config and reconcile:

python3 ${CLAUDE_SKILL_DIR}/scripts/derive_figure_legend_counts.py \
  --flow-config figures/figure1_strobe_graphviz.yaml \
  --manuscript manuscript/index.qmd \
  --out qc/figure_legend_counts.json --strict

Any n = N in the caption that is not a box count in the flow config is a MISMATCH (stale caption) — update the caption from the config, never the reverse. This pairs with numerical-safety's "re-derive prose counts every revision" rule and with /sync-submission's cross-document N checks. (The reconciler is stdlib-only and parses the config as text, so it works regardless of the flow tool.)

Calibration Plot

• 45-degree reference line (perfect calibration).
• Grouped observed vs predicted with error bars.
• Report Hosmer-Lemeshow statistic and Brier score in annotation.
• Optional: histogram of predicted probabilities at the bottom.

Kaplan-Meier Curve

• Step function with distinct colors per group.
• Censoring marks as small vertical ticks.
• Number-at-risk table below the plot (aligned with x-axis ticks).
• Log-rank p-value in annotation.
• Median survival with 95% CI if applicable.

Bland-Altman Plot

• X-axis: mean of two measurements.
• Y-axis: difference between measurements.
• Horizontal lines: mean difference (solid), +/-1.96 SD (dashed).
• Annotate the mean diff and limits of agreement values.
• Optional: proportional bias check (regression line through points).

Confusion Matrix

• Heatmap with both counts and percentages in each cell.
• Row-normalized percentages preferred (sensitivity per class).
• Clear axis labels: "Predicted" (x) and "Actual" (y).
• Use sequential colormap (Blues or Greens), not diverging.

Box/Violin Plot

• Show individual data points (jittered) overlaid on box or violin.
• Mark median and mean distinctly.
• Statistical annotation brackets with significance stars.
• Stars: p<0.05, p<0.01, ** p<0.001, ns for non-significant.

Pipeline Diagram

• Horizontal or vertical flow of processing stages.
• Boxes: rounded rectangles with stage name and brief description.
• Arrows: labeled with data counts or transformation type.
• Color-code stages by category (data collection, processing, validation).
• Keep text minimal; use supplementary caption for details.

Bar Chart

• Error bars: 95% CI (preferred) or SD, stated in caption.
• Individual data points overlaid if n < 30.
• Horizontal orientation for many categories.
• Sort by value (descending) unless order is meaningful.

Heatmap

• Annotate cells with values.
• Use sequential colormap for correlation (coolwarm diverging if centered at zero).
• Mask diagonal for correlation matrices.
• Cluster rows/columns if appropriate.

---

Style Rules

Colors

Wong colorblind-safe palette (default):

WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']

Sequential palettes (for heatmaps):

• Positive values: Blues or Greens
• Diverging (centered at 0): coolwarm or RdBu_r
• Agreement matrices: YlOrRd

Rules:

• Never use red-green only distinctions.
• Use line style (solid, dashed, dotted) in addition to color for line plots.
• Use marker shape in addition to color for scatter plots.

Typography

• Font family: Arial or Helvetica (sans-serif).
• Panel labels: uppercase bold letter, top-left of each panel.

Layout

• Minimize white space while maintaining readability.
• Align multi-panel figures on a grid.
• Consistent axis ranges across comparable panels.
• No figure titles in the plot itself (title goes in the caption below).

Statistical Annotations

• Significance stars: p<0.05, p<0.01, ** p<0.001
• Place above comparison brackets.
• Report exact p-value in the figure legend or caption, not in the plot.
• For AUC, correlation, or agreement: display in the legend with 95% CI.

---

Journal Specifications

Default dimensions (override from figure_specs.md if journal-specific):

• Single column: 3.5 in (88 mm) width
• 1.5 column: 5.0 in (127 mm) width
• Double column: 7.0 in (178 mm) width
• Full page: 7.0 x 9.5 in (178 x 241 mm)
• DPI: 300 minimum for halftone, 600 for line art
• File formats: PDF (vector, preferred) + PNG (300 DPI)
• No chartjunk: no 3D effects, no unnecessary gridlines, no decorative elements, no gradient fills

---

Multi-Panel Figures

For composite figures with multiple panels:

fig, axes = plt.subplots(nrows, ncols, figsize=(width, height))

# Label each panel
for ax, label in zip(axes.flat, 'ABCDEFGH'):
    ax.text(-0.15, 1.05, label, transform=ax.transAxes,
            fontsize=12, fontweight='bold', va='top')

Common layouts:

• 2-panel horizontal: figsize=(7.0, 3.5), 1 row x 2 cols
• 2-panel vertical: figsize=(3.5, 7.0), 2 rows x 1 col
• 2x2 grid: figsize=(7.0, 7.0), 2 rows x 2 cols
• 3-panel: figsize=(7.0, 3.0), 1 row x 3 cols

Use plt.tight_layout() or fig.subplots_adjust() for spacing.

---

Caption Writing

After generating each figure, draft a caption following these rules:

1. First sentence: Describe what the figure shows (type + key finding). 2. Subsequent sentences: Define abbreviations, explain symbols, state sample sizes. 3. Statistical details: Note the test used and significance threshold. 4. Format: "Figure {N}. {Caption text}" -- no bold, no title case.

Example:

Figure 1. Receiver operating characteristic curves comparing the diagnostic performance of

the multi-agent pipeline (blue) and single-agent baseline (orange) for identifying incorrect

Anki flashcard content. The area under the curve was 0.92 (95% CI: 0.89-0.95) for the

multi-agent pipeline and 0.84 (95% CI: 0.80-0.88) for the single-agent baseline (DeLong

test, p = 0.003). The dashed diagonal line represents chance performance.

---

Skill Interactions

---

Error Handling

• If data is insufficient for the requested figure type, explain what is needed and ask the user.
• If a figure exceeds journal dimension limits, resize and report the adjustment.
• If text overlaps in the figure, try tight_layout(), reduce font size, or adjust spacing.
• Never fabricate data points. If sample data is needed for a template demo, explicitly label it as "example data."

CLI Tools Available

ImageMagick, Ghostscript, FFmpeg are installed and can be used for post-processing:

# Figure DPI/format conversion for journal submission
magick input.png -density 300 -units PixelsPerInch output.tiff
magick input.png -resize 1200x -quality 95 output.jpg

# CMYK conversion (some print journals require this)
magick input.png -colorspace CMYK output.tiff

# Multi-panel figure assembly (A/B/C/D panels)
magick montage panelA.png panelB.png panelC.png panelD.png \
  -tile 2x2 -geometry +10+10 -density 300 combined.png

# Animated figure (GIF from frame sequence)
ffmpeg -framerate 2 -i frame_%03d.png -vf "scale=800:-1" output.gif

# Video from figure sequence (for supplementary materials)
ffmpeg -framerate 1 -i slide_%03d.png -c:v libx264 -pix_fmt yuv420p supplementary_video.mp4

AI Image Generation (Optional)

AI illustration is a supplementary option, not a requirement. Visual abstracts and figures can be completed without any API key using study figures and free illustration libraries.

If GEMINI_API_KEY is set, the generate_image.py script can generate illustrations:

python ${CLAUDE_SKILL_DIR}/scripts/generate_image.py \
  "Clean medical illustration of a CT-guided lung biopsy procedure, \
   flat vector style, white background, no text" \
  --output output.png --aspect 16:9

Use for: procedural schematics, anatomical illustrations, pipeline diagrams. Always review AI output against the AI-Generated Figure Warning section above.

If GEMINI_API_KEY is not set, guide the user to free illustration resources: see ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md.

Language

• Code and figure text: English
• Communication with user: Match user's preferred language
• Medical terms: English only

Anti-Hallucination

• Never fabricate references. All citations must be verified via /search-lit with confirmed DOI or PMID. Mark unverified references as [UNVERIFIED - NEEDS MANUAL CHECK].
• Never invent clinical definitions, diagnostic criteria, or guideline recommendations. If uncertain, flag with [VERIFY] and ask the user.
• Never fabricate numerical results — compliance percentages, scores, effect sizes, or sample sizes must come from actual data or analysis output.
• If a reporting guideline item, journal policy, or clinical standard is uncertain, state the uncertainty rather than guessing.

Critic Rubric — Data Plots

Apply this rubric when the generated figure is a data visualization (not a flow diagram): ROC, forest, KM, calibration, Bland-Altman, confusion matrix, box/violin, bar, heatmap. The Claude session should Read the rendered PNG plus any available exemplars from references/exemplar_diagrams/{type}/, then mark each item below as PASS / PARTIAL / FAIL with a one-line justification.

After scoring, produce a list of concrete matplotlib/seaborn edits that would resolve every FAIL or PARTIAL item. Return the scored rubric + edit list to the user.

---

A. Axes, labels, units

1. X-axis label present with units where applicable. 2. Y-axis label present with units where applicable. 3. Axis tick labels readable (no overlap, sensible density, no scientific notation where plain numbers fit). 4. Axis limits sensible — no wasted whitespace (e.g., ROC axes should be 0–1 exactly, forest plot x-axis should frame all CIs without clipping). 5. Tick direction inward, tick marks minor/major where needed. No chart-spine clutter.

B. Legend / caption

6. Legend present when ≥2 series are shown; placed where it does not obscure data. 7. Legend labels are descriptive (not "Series 1"); include N or group size where relevant. 8. Legend ordering matches visual order of series (top to bottom). 9. Caption-ready — plot does not rely on external notes the caption cannot repeat concisely.

C. Figure-type–specific requirements

ROC curve

• AUC and 95% CI displayed on plot or in legend
• Diagonal reference line (chance) shown
• Sensitivity on Y-axis (0–1), 1−Specificity on X-axis (0–1)
• Multiple models distinguished by color AND line style (grayscale-safe)

Forest plot

• Effect estimates aligned to a vertical reference line (null effect)
• CIs drawn as horizontal bars with appropriate caps
• Box size proportional to study weight
• Diamond summary at the bottom; pooled estimate and CI printed
• Left column: study labels; right column: effect (95% CI) numeric
• Heterogeneity statistics (I², τ², Q p-value) reported in caption or plot

KM curve

• Number at risk table below the plot
• Median survival and its CI shown or reported in caption
• Log-rank p-value or Cox HR reported
• Curves distinguishable in grayscale (line style + color)
• Censoring marks visible

Calibration plot

• Ideal diagonal line (y=x) shown
• Binned observed vs. predicted points
• Hosmer-Lemeshow p-value or Brier score reported
• Histogram of predicted probabilities overlaid or beside the plot

Bland-Altman

• Mean difference line
• ±1.96 SD limits of agreement
• LoA values printed
• Scatter points not clipped at plot edges

Confusion matrix

• Cells annotated with counts AND percentages
• Axis labels "Predicted" / "Actual" (or "Reference")
• Diagonal emphasized (darker color or heavier stroke) if useful

D. Typography and accessibility

10. Font size ≥ 8pt at final dimensions (most journals require 6–7pt min for axis numerics, 8pt for labels). At 300 DPI in a 3.5×3.5 inch figure, this corresponds to roughly ≥25 px — use critic_figure.py OCR min-height flag as a proxy. 11. Single font family throughout (typically sans-serif). No mixed Arial/Helvetica/Times. 12. Colors from Wong palette or equivalent colorblind-safe scheme. critic_figure.py flags out-of-palette fractions >15%. 13. Grayscale-safe — every series is distinguishable in grayscale conversion, either through line style, marker shape, or luminosity differences.

E. Publication readiness

14. Vector PDF produced in addition to PNG. 15. Dimensions match journal spec — width per figure_specs.md for the target journal (single column ≈3.5 in, double ≈7.0 in). 16. DPI ≥ 300 (halftone) or ≥ 600 (line art). 17. No duplicate data encoding (e.g., color + shape + size all mapped to the same variable adds clutter without information). 18. Statistical annotations — where significance markers are used (*, **, ***), the caption defines thresholds. Prefer actual p-values for publication.

F. Exemplar comparison (if exemplars exist for this type)

For non-flow types, the worked anatomy models live in ../exemplar_plots/ (e.g., forest_plot.md) — read the matching one and confirm the draft has every element it lists.

19. Visual density comparable to exemplars — not significantly sparser or more cluttered. 20. Annotation style — placement of summary statistics, N labels, p-values consistent with exemplars.

G. Medical AI / prediction-model checks (added v1.1.0)

Apply when the figure supports a prediction-model or medical-AI claim (TRIPOD+AI, CLAIM 2024, STARD-AI, CONSORT-AI). Source: reporting_guideline_figure_map.md "AI-specific figures most often missing."

21. Calibration plot accompanies discrimination — when the manuscript reports AUC/c-statistic, a calibration plot is also presented (or the figure is paired with one). TRIPOD+AI mandates calibration; AUC alone is insufficient evidence of model fitness. 22. Subgroup / fairness panel — when the deployment claim covers multiple demographic groups, sites, or scanner vendors, performance is shown stratified by at least one such axis. CLAIM 2024 §C and TRIPOD+AI both require this. 23. Colorblind-safe + redundant encoding — color carrying diagnostic meaning is paired with at least one non-color cue (line style, marker shape, or direct label) so the figure survives deuteranopia simulation and grayscale conversion. (Crameri 2024.) Stronger than the existing item D.13. 24. Dataset-flow visible — for AI papers reporting performance on a test set, the manuscript also includes a dataset-flow diagram with counts at training / tuning / internal-test / external-test splits. Required by STARD-AI, CLAIM 2024, TRIPOD+AI. If the figure under review is not the dataset-flow itself, confirm one exists elsewhere in the manuscript. 25. Decision-curve analysis (when claiming clinical utility) — papers that argue "this model would change clinical management" must accompany discrimination/calibration with a decision-curve plot (Vickers & Elkin, Med Decis Making 2006). Recommended by TRIPOD+AI.

---

Scoring output format

## Critic report (data plot, round T)

| Item | Score | Note |
|------|-------|------|
| A.1 X-axis label | PASS | — |
| A.2 Y-axis label | FAIL | Missing units ("Sensitivity" should be unitless OK; but "Time" needs "(months)") |
| ...

### Required edits before next render
1. Add unit "(months)" to Y-axis label.
2. Increase legend font from 6pt to 8pt.
3. ...

### Overall verdict
[ ] PASS — ready for manuscript
[ ] REFINE — items above must be fixed before next round

Record critic_pass: yes | partial | no and refine_rounds: N in the _figure_manifest.md for this figure after the final round.

Critic Rubric — Flow Diagrams

Apply this rubric when the generated figure is a flow diagram: STARD, CONSORT, PRISMA, or pipeline/methods. The Claude session should Read the rendered PNG plus any available exemplars from references/exemplar_diagrams/{stard|consort|prisma|pipeline}/, then mark each item below as PASS / PARTIAL / FAIL with a one-line justification.

After scoring, produce a concrete list of source edits (D2 code changes, node label fixes, count corrections) that would resolve every FAIL or PARTIAL item. Return the scored rubric + edit list to the user.

---

A. Structural integrity

1. Box overlap — No two boxes or text labels overlap. Arrows do not cross through node text. 2. Readable edges — Every edge has a clear source and target; direction is unambiguous; no dangling arrows. 3. Hierarchy preserved — Vertical or horizontal flow reads in a single dominant direction; upstream nodes appear before downstream ones. 4. Alignment — Peer nodes at the same logical level are aligned (baseline or center). 5. Whitespace — No excessive vertical gap (>2× box height) between sequential steps. No cramped collisions at decision points.

B. Required elements (per figure type)

STARD flow (diagnostic accuracy)

• Enrollment count (consecutive vs. random, eligible n)
• Included n (with inclusion criteria applied)
• Excluded n with itemized reasons
• Index test performed (n analyzed)
• Reference standard performed (n analyzed)
• Final analysis cohort (n with both tests)

CONSORT flow (RCT)

• Enrollment section: Assessed for eligibility (n), Excluded (n with

reasons: did not meet criteria, declined, other)

• Allocation section: Randomized (n), Allocated to each arm (n received /

n did not receive intervention)

• Follow-up section: Lost to follow-up (n, reasons), Discontinued (n,

reasons) per arm

• Analysis section: Analyzed (n), Excluded from analysis (n, reasons)

per arm

PRISMA 2020 flow (systematic review)

• Records identified from databases (n per database)
• Records identified from other sources (registers, citation search, etc.)
• Records after duplicates removed (n)
• Records screened (n) → Records excluded (n)
• Reports sought for retrieval (n) → Reports not retrieved (n)
• Reports assessed for eligibility (n) → Reports excluded with reasons (n, reason categories)
• Studies included in review (n) / Reports of included studies (n)

Pipeline / methods

• Input data block clearly named (modality, cohort)
• Preprocessing steps in sequence (resampling, normalization, augmentation)
• Model / algorithm block with name or architecture
• Output / task block (segmentation, classification, regression)
• Evaluation metric block where applicable

C. Numerical consistency

6. Arithmetic balance — At each branching node, in = out + excluded. Verify every subtraction explicitly. Flag any mismatch. 7. Column totals consistent — For parallel arms (CONSORT), arm totals sum to the randomized total at every stage. 8. No duplicate counts — A participant should not appear in two leaf nodes unless the diagram explicitly models this. 9. Manuscript consistency — Numbers in the diagram match the corresponding text in Methods/Results (apply the [VERIFY-CSV] rule — every count should trace to a CSV cell or source query).

D. Typography and accessibility

10. Font size ≥ 18pt at the compact-recipe render dimensions (main boxes ≥ 20pt, exclusion boxes ≥ 18pt, italic notes ≥ 17pt). Check against the critic_figure.py OCR min-height flag. 11. No truncated text — No box shows clipped text ("Assessed for eli..."). OCR coverage check (source_word_coverage ≥ 0.95). 12. Consistent casing — Sentence case everywhere, or Title Case everywhere — not mixed. 13. Wong palette or neutral only — Fill colors drawn from the Wong colorblind-safe set plus whites/light grays. No red-green only distinctions. 14. Grayscale-safe — Conversion to grayscale preserves all distinctions between box categories (intent vs. exclusion vs. outcome).

E. Publication readiness

15. Vector format available — Both PNG (for DOCX embedding) and PDF (for journal submission) were produced. If PDF missing, flag. 16. Dimensions match journal spec — Width matches the target journal's single-column or double-column specification (±0.3 in). 17. DPI meets spec — ≥600 DPI for line-art submissions, ≥300 DPI for halftone. 18. Policy compliance — Tool is D2 or a permitted auto-layout engine, not matplotlib FancyBboxPatch and not Mermaid. (Mermaid is forbidden in papers per the project's figure-toolchain policy.)

F. Exemplar comparison (if exemplars exist for this type)

19. Hierarchy depth matches one of the exemplars within ±1 level. 20. Typographic weight — Main step labels are visually heavier (bold/larger) than parenthetical / exclusion labels, as in the exemplars. 21. Emphasis placement — Key cohort counts (final analysis n, primary outcome n) are visually emphasized (thicker stroke, larger font, or fill distinction), consistent with exemplar conventions.

G. Communication-first checks (added v1.1.0)

These checks operationalize references/design_principles.md (Nature Hum Behav 2026) and references/flow_diagram_lessons.md. Apply when the diagram will be circulated to senior co-authors or submitted to a peer- reviewed venue.

22. Cognitive load — Each column has ≤7 boxes; each diagram uses ≤3 distinct shapes (e.g., rectangle / rounded rectangle / note) and ≤3 fill colors. If the count is exceeded, fold detail into supplementary or split into a multi-panel figure. 23. Key-message visibility — The analytic cohort (final n included in primary analysis) is visually emphasized via thicker stroke (penwidth ≥ 1.8), distinct fill, or larger font, so the reader's eye lands on it within 2 seconds. 24. Official-template fidelity (when applicable) — Layout matches the canonical PRISMA 2020 / CONSORT 2010 / STARD 2015 / STROBE template used by the corresponding statement group. Custom layouts are acceptable for exploratory drafts but must be replaced before circulation. (See flow_diagram_lessons.md Lesson 1.) 25. Exclusion-box geometry — Exclusion side-boxes are rectangles (not shape: note / "dog-ear" style) when the diagram aims to match PRISMA / CONSORT canonical look. Bullets within exclusion boxes are left-aligned (Graphviz \l, not \n). 26. Frozen-version sync — The figure file path includes the manuscript version (figures/v{N}/figure_1.pdf) and the value of v{N} matches the current manuscript version. Edits after circulation must branch to v{N+1}/, never overwrite v{N}/. (See flow_diagram_lessons.md Lesson 5.)

---

Scoring output format

## Critic report (flow diagram, round T)

| Item | Score | Note |
|------|-------|------|
| A.1 Box overlap | PASS | — |
| A.2 Readable edges | PASS | — |
| ...
| C.6 Arithmetic balance | FAIL | Enrollment 500 ≠ Included 420 + Excluded 85 (off by 5) |
| ...

### Required edits before next render
1. Correct Excluded count in node X from 85 to 80.
2. Increase font-size of "Analysis" subsection header from 18 to 22.
3. ...

### Overall verdict
[ ] PASS — ready for manuscript
[ ] REFINE — items above must be fixed before next round

Record critic_pass: yes | partial | no and refine_rounds: N in the _figure_manifest.md for this figure after the final round.

Effective Scientific Figure Design

Primary source: Brunner et al., "Designing effective figures for

scientific communication." Nat Hum Behav (2026).

DOI: 10.1038/s41562-026-02466-9 — communication-context strategies.

>

Companion sources (cite in figure legends / Methods when used):

- Rougier et al., "Ten simple rules for better figures." *PLoS Comput

Biol* 2014;10:e1003833 (PMID 25210732). General-purpose, foundational

ten-item checklist.

- Crameri F., "Choosing the right colors: a perceptually uniform,

colorblind-safe approach." Curr Protoc 2024;4:e1126

(DOI 10.1002/cpz1.1126). Definitive 2024 reference for viridis,

cividis, batlow palettes and redundant encoding.

>

Triggered from: SKILL.md Step 1 ("Specify"). Read this file before

choosing a figure type — it shifts focus from "which chart fits the data" to

"what message should the reader walk away with."

Most figure-design guidance focuses on technical execution (axis ranges, palettes, DPI). This file complements that by adding a communication-first layer: who reads the figure, under what time pressure, and what should they remember 10 seconds later. Apply these strategies in Step 1 when specifying a figure; revisit during Step 4 / 4b when reviewing.

---

The 5 strategies (read in order)

1. Identify the key message (most important)

Before opening a plotting library, write one sentence describing what the figure must convey. If you cannot, the figure is premature. Examples:

• "Model A outperforms Model B at every operating threshold."
• "Adverse-event rates differ by route of administration but not by dose."
• "The proposed pipeline runs end-to-end in under 30 seconds per case."

Pin that sentence as a comment at the top of the generation script. Every panel, color, annotation, and label exists to support that message; anything that does not should be removed or moved to supplementary material.

2. Consider time and interaction (audience-aware)

Different reading contexts allow different amounts of inspection time:

Set the reading-time budget in Step 1, then design backwards. If the same result will appear in a journal article and a conference talk, build two distinct versions — the conference version usually drops half of what the journal version contains.

3. Choose the right graph type and use color intentionally

The graph type should match the structure of the data, not aesthetic preference.

Color rules (compatible with this skill's figure_specs.md; full justification in Crameri 2024):

• Categorical groups: Wong palette (8 colorblind-safe colors).
• Sequential magnitude: viridis or cividis (perceptually uniform,

colorblind-safe). Avoid jet and rainbow — they introduce false perceptual edges.

• Diverging around zero: RdBu, PuOr, or vik (Crameri).
• Encode meaning, not decoration. If the same conclusion holds in

grayscale, color is decorative — remove or use neutral grays.

• Redundant encoding when color carries diagnostic information: pair

color with line style, marker shape, or direct label so the figure survives a deuteranopia simulation and a black-and-white print.

• Maximum 3 colors per panel unless the data structure genuinely demands

more (and then label each directly, not via legend).

4. Reduce cognitive load

Every visual element competes for attention. The reader's working memory is roughly 7 items; design under that ceiling.

• ≤7 distinct visual elements per panel (curves, boxes, annotations).
• ≤3 distinct shapes (e.g., square, circle, triangle).
• ≤3 colors as above.
• Direct labels on series > legend. Legend lookups cost ~2 seconds each.
• No 3-D, drop-shadow, gradient fill, or rotated axis labels unless they

encode data.

• Sans-serif font ≥ 9 pt at print size; ≥ 18 pt for slides; ≥ 24 pt for

posters.

• Whitespace is not wasted space — it groups related elements.

If a panel violates two or more of these, split it into multiple panels or move detail to supplementary material.

5. Ask whether a figure is really needed

Sometimes a table, a single sentence, or a caption-only number conveys the result more clearly. Use a figure when at least one of the following is true:

• The reader needs to perceive a shape (trend, distribution, threshold).
• The reader needs to compare across many groups simultaneously.
• The result depends on a spatial or anatomical relationship.
• The audience will not read the prose carefully and needs a visual hook.

Otherwise, prefer a small table or in-line text. A 3-row × 2-column results table beats a bar chart of two values.

---

Decision: figure vs table

When in doubt, sketch both on paper for 60 seconds and decide which the eye finishes first.

---

Cognitive load checklist (Step 4 quick scan)

• [ ] One sentence describes the key message in the script comment.
• [ ] Reading-time budget matches the deployment context.
• [ ] ≤7 visual elements per panel.
• [ ] ≤3 colors carrying meaning (not decoration).
• [ ] No 3-D / shadow / gradient unless data-driven.
• [ ] Direct labels on series; legend has ≤4 entries.
• [ ] Font size meets context minimum (9 pt print / 18 pt slide / 24 pt poster).
• [ ] Same figure works in grayscale (run a convert -colorspace Gray test).

If two or more boxes are unchecked, return to Step 1 before exporting.

---

Anti-patterns (drawn from this skill's critic rubrics)

These compose with the more granular checks in critic_rubrics/data_plot.md and critic_rubrics/flow_diagram.md:

• Default-palette syndrome — using the matplotlib tab10 palette without

thought. Reads as a quick draft, not a finished figure.

• Legend-dependence — colored series without direct labels, forcing

back-and-forth between legend and data.

• Decorative 3-D — bars or pies in 3-D with no third data dimension.
• Chart-of-three-values — figure where a sentence would be clearer.
• Caption-as-Methods — caption explains how the data were generated

rather than what to look at; methodology belongs in the Methods section.

• Mismatched detail — slide-deck figure rendered at 6 pt because it was

copied from the manuscript without adjustment.

---

Cross-references

• critic_rubrics/data_plot.md — quantitative critic checks for non-flow figures
• critic_rubrics/flow_diagram.md — extended checks for flow diagrams
• figure_specs.md — journal-specific dimensions and DPI
• flow_diagram_lessons.md — production lessons specific to PRISMA / CONSORT / STARD
• reporting_guideline_figure_map.md — which figures CONSORT-AI / TRIPOD+AI / CLAIM 2024 / STARD-AI mandate
• pipeline_concepts_medical_ai.md — DICOM workflow, annotation, federated learning, model architecture conventions

consort Exemplars

This directory will hold 3–5 hand-curated consort flow/figure exemplars. Use the extraction script to add one:

python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
    --pdf "/path/to/paper.pdf" \
    --page N \
    --type consort \
    --label LastnameYEAR_CONSORT \
    --doi 10.xxxx/yyyy

See ../README.md for curation guidelines.

Why this exemplar is good — other_02 (bubble chart landscape)

Hierarchy / structure: A landscape scatter/bubble chart with time on the X-axis (pre-2022 → 2025) and MMLU score on the Y-axis. A dashed logistic-like trajectory connects the frontier models across years, implicitly communicating the field-wide progression without a separate annotation layer.

Whitespace & balance: The pre-2022 region is nearly empty by design — the sparseness is informative, not wasted. High-performance cluster in 2024–2025 is where bubbles densely overlap, and the axis range (0–100 MMLU) leaves enough headroom above the top models to signal the 90%+ ceiling.

Typography (font size, weight, alignment): Model names are placed adjacent to their bubbles with consistent font size; no leader lines are needed because the labels sit directly on or beside each dot. The reference lines ("85% = human expert", "70% = ideal") are low-contrast gray so they guide without competing.

Emphasis (which elements are visually strongest, why): Bubble size encodes release prominence, and color encodes the parent organization — two independent visual channels that give the reader a comparative read without returning to the legend.

Color usage: Eight distinct organizational colors placed against a white field. The palette is high-saturation but the bubbles are translucent, which lets overlapping dots remain legible.

Weaknesses (if any — nothing is perfect): The legend (top) is cramped and would benefit from more horizontal space. A few labels ("DeepSeek", "Claude 3.5 Sonnet") clip against neighbors in the 2024 cluster. No explicit units or source note in the rendered crop.

Why this exemplar is good — pipeline_01 (pipeline)

Hierarchy / structure: A clean left-to-right pipeline — paired inputs (CXR image on top, clinical text on bottom) merge into a single downstream processor (MLLM) and terminate in a single output box. The two parallel encoder boxes are aligned horizontally, which communicates multimodal symmetry at a glance.

Whitespace & balance: Generous horizontal whitespace around the central MLLM chip icon makes it the visual anchor. Input column and output column carry roughly equal ink weight, avoiding a lopsided read.

Typography (font size, weight, alignment): Box labels (Image encoder / Text encoder) are bolded sans-serif; patient demographics use a smaller mono-like face to read as tabular data rather than prose. Illustrative "clinical question" is italicized and color-accented to flag that it is an example, not a label.

Emphasis (which elements are visually strongest, why): Pink-tinted inputs and green output speech bubble draw attention to the clinically meaningful endpoints (question in → answer out), while the technical processing blocks sit in neutral gray.

Color usage: Two saturated tints (pink for input, green for output) plus neutral gray for machinery. Colorblind-safe if converted — the saturation contrast survives grayscale.

Weaknesses (if any — nothing is perfect): The MLLM "chip" icon is decorative rather than structural; could confuse readers expecting an architectural diagram. CXR thumbnail is small relative to the clinical-info panel, slightly under-weighting the image modality.

Why this exemplar is good — pipeline_03 (pipeline)

Hierarchy / structure: Two-panel layout (A and B) separated by a thin vertical rule, with each panel self-contained. A shows contrastive pre-training: text encoder (top) and image encoder (bottom) converge on a similarity matrix. B shows a VQA inference pipeline flowing left → right. Panel labels sit in the top-left corner of each panel at a consistent position.

Whitespace & balance: Margins around the similarity matrix give it room to read as a data object rather than decoration. The two panels carry roughly equal visual mass so neither dominates.

Typography (font size, weight, alignment): Box labels use uniform sans-serif at one size; the similarity matrix cells use a mono face so Tᵢ·Iⱼ products align as a grid. The CXR/report thumbnails carry subscripts (T₁, T₂, I₁, I₂) in the same font as the matrix cells — visually tying the inputs to the matrix rows/columns.

Emphasis (which elements are visually strongest, why): The diagonal of the similarity matrix is shaded darker, pulling the eye to the positive pairs — this is the pedagogical point of contrastive learning and the figure lets design carry the explanation.

Color usage: Pink for text-side components, blue for image-side components. This two-channel color coding is consistent across both panels and makes the multimodal symmetry self-evident.

Weaknesses (if any — nothing is perfect): Panel B's projection matrix W and token boxes are compressed; readers unfamiliar with contrastive-language-image architecture may need to read the caption closely. The "language instruction" box on the far right of B is visually detached from the main flow.

Why this exemplar is good — pipeline_04 (pipeline)

Hierarchy / structure: Top row is the macro view (modality inputs → encoder → connector → LLM → generator → outputs), bottom row zooms into the "connector" block with four named variants (A MLP, B Q-Former, C MH-Attn, D Expert Captioning). A light-blue downward arrow visually tethers the macro block to its expansion — the classic "zoom-in detail" device applied cleanly.

Whitespace & balance: Even horizontal spacing between connector variants. The expanded lower panel is framed in a subtle tinted rectangle that contains it without drawing attention.

Typography (font size, weight, alignment): Consistent sans-serif labels throughout. Capital letters A/B/C/D tag the four variants in one size; component labels (MLP, Q-Former, MH-Attn) use the same type family as the macro row for continuity.

Emphasis (which elements are visually strongest, why): The central LLM box is the largest and darkest block — correctly, because this is the figure's conceptual center. The connector variants underneath share equal weight, communicating their parallel status as alternatives rather than a sequence.

Color usage: Restrained three-tone palette (blue for neural modules, orange for learnable queries/tokens, gray for data I/O). Dashed outlines mark optional/repeated elements. Colorblind-safe.

Weaknesses (if any — nothing is perfect): Many modality icons (image/audio/video) repeat at both input and output; a single output cluster would reduce clutter. The Q/K/V labels inside panel C are small relative to neighboring elements.

Why this exemplar is good — pipeline_05 (pipeline / tasks illustration)

Hierarchy / structure: Two stacked panels (A and B), each a four-column table-like layout. A shows report generation for two cases (pelvic radiograph and abdominal CT) side-by-side: input → reference report → generated report. B shows VQA with closed-ended vs. open-ended question variants for each case. The uniform column structure makes the cross-row comparison immediate.

Whitespace & balance: Narrow column gutters (not wasteful) but generous vertical spacing between cases. Each row reads as a discrete case study.

Typography (font size, weight, alignment): The strongest typographic choice is the use of colored highlights on specific phrases in the generated reports — green for confirmed findings, red for hallucinated content, orange for partial matches. This converts what would be plain prose into an annotated diff without extra legend burden, provided the reader notices the color key.

Emphasis (which elements are visually strongest, why): The color-annotated report text is the primary didactic payload and is the strongest element, correctly. The input images serve as context and are sized accordingly smaller.

Color usage: Color communicates semantic agreement/disagreement in text — a rare and effective use. Panel A uses gray scaffolding (headers, borders) to keep attention on the colored content.

Weaknesses (if any — nothing is perfect): Red and green are the primary discriminators, which is not colorblind-safe. A shape or weight encoding (bold for hallucinations) would make it more accessible. Font size of the report text is small; readability at small figure widths could suffer.

Why this exemplar is good — pipeline_06 (pipeline / M3D architecture)

Hierarchy / structure: Strict top-to-bottom flow. Volumetric CT input (single modality box with three anatomical sub-panels) feeds a 3D image encoder; parallel text-side question templates feed the text tokenizer. Both streams converge on a single LLM-with-LoRA block, then split into two downstream heads (report generation, VQA). The shape (funnel in → funnel out) mirrors the dual-task architecture.

Whitespace & balance: Equal space allocated to image-side and text-side inputs; the LLM block spans the full width to signal it is the shared backbone. Tight but not cramped.

Typography (font size, weight, alignment): Bolded section headers (Report Generation / VQA) for the prompt boxes; prompt contents in a slightly smaller, clearly italic-or-lighter weight. The special tokens (<|eot_id|>, <|start_header_id|>) use a monospace face — the right choice for communicating that they are literal code strings.

Emphasis (which elements are visually strongest, why): The fire/snow icons (trainable/frozen) are placed on individual components, making the training-recipe claim visually inspectable. This is a small but high-value design choice — readers can audit the method by looking at the figure.

Color usage: Cool blues for vision modules, warm pinks for language/prompt modules. Two-tone palette scales well to grayscale (luminance differs).

Weaknesses (if any — nothing is perfect): The "trainable/frozen" legend sits in the upper right and may be missed by readers who scan left-to-right top-down. The three CT sub-views (chest/abdomen/pelvis) are small enough that anatomy is only suggested.

Why this exemplar is good — pipeline_07 (pipeline / MAIRA-Seg)

Hierarchy / structure: A horizontal pipeline with input row (CXRs, pseudo-masks, task instruction, textual context) on top, processing row (image encoder, segmentation model, tokenizer/embedding) in the middle, and convergence on a single LLM block at the bottom. The vertical progression communicates "modalities in → unified tokens → one model out" without ambiguity.

Whitespace & balance: The LLM block spans almost full width as a visual foundation. Upper row inputs are grouped by modality with clear gaps, avoiding the "everything dumps in" look.

Typography (font size, weight, alignment): Small but uniform sans-serif labels; auxiliary labels ("Only in multi", "Pseudo-labels") are italic to mark them as conditional annotations without adding a legend.

Emphasis (which elements are visually strongest, why): The LLM base block is the largest uniform colored rectangle — visually grounding the whole system as one model. Fire icons on trainable components again let the figure double as a training-recipe specification.

Color usage: Warm pinks for segmentation/prompt-side modules; cool blues for vision/LLM modules. Dashed borders denote optional paths ("Only in multi"). Consistent with the color code used in other architecture figures in the paper.

Weaknesses (if any — nothing is perfect): The dense upper input row competes for attention; a subtle grouping box or lane separator would help. The segmentation-tokens-extractor sits off the main flow axis, which introduces a jog in the layout that briefly interrupts the top-down read.

Why this exemplar is good — pipeline_08 (pipeline / CLIMB foundation model)

Hierarchy / structure: Three-stage landscape layout separated by vertical rules: Training (left) | Specialized Encoder (center) | Testing + Downstream (right). Inside the Training panel, three modality lanes (Graphs, 1D signals, 2D&3D images) each carry three exemplar thumbnails, creating a grid-of-grids that communicates breadth without listing every dataset.

Whitespace & balance: Equal vertical space per modality lane; the encoder column is visually narrow to read as a bottleneck/convergence point. Right-side testing block has enough margin around the OOD dataset callout to keep it distinct.

Typography (font size, weight, alignment): Modality headers (Graphs, 1D signals, 2D&3D images) are larger and bolder than thumbnail captions. Section headers (Training / Testing) sit above their column in matching weight.

Emphasis (which elements are visually strongest, why): The thumbnail grid at training time is the strongest visual payload — it answers "what does multimodal breadth look like?" in one glance. The encoder column is intentionally understated because it is a conceptual stage, not a specific architecture.

Color usage: Subtle pastel backgrounds separate stages (soft pink for training, green for testing, peach for downstream) without compromising the thumbnails' own color. Downstream task illustrations (physician + patient) add warmth without clutter.

Weaknesses (if any — nothing is perfect): Ten or more thumbnail captions at small sizes risk clipping on reprints. The "transfer" and "finetuned" arrows in the testing column could be slightly thicker to read as a pipeline rather than decoration.

Why this exemplar is good — pipeline_09 (evaluation-metrics comparison)

Hierarchy / structure: A 3×2 grid where all six evaluation methods share identical sub-layout — method title (bar header), candidate excerpt (middle), and two-bullet summary (O = what is captured, △ = what is missed). One shared reference sentence sits above the grid, establishing the common ground-truth all six metrics are being compared against.

Whitespace & balance: The top reference strip spans full width and is visually distinct from the grid below. Within each cell, internal padding is consistent and there is clear separation between the colored header bar and the body — giving each metric equal visual real-estate.

Typography (font size, weight, alignment): Bold uppercase metric names in colored header bars; candidate text below in regular weight with discriminating phrases colored inline (e.g., "right-sided" in red for a miss). The O/△ legend uses symbols instead of words, keeping each cell compact.

Emphasis (which elements are visually strongest, why): The six colored header bars act as chapter tabs, making the grid scannable. Colored phrases inside the candidate text are the didactic focus — they show precisely what each metric is scoring.

Color usage: Six distinct pastel headers, chosen for differentiation rather than semantic meaning. Candidate-text color (red/green/blue) is semantic. Palette is varied but low-saturation enough to avoid fatigue.

Weaknesses (if any — nothing is perfect): Six colors with no ordinal relationship could be reduced; the reader doesn't need to distinguish cells by color since the grid layout already separates them. Semantic text colors (red for missed) overlap with header colors in a few cells.

Why this exemplar is good — pipeline_10 (clinical integration overview)

Hierarchy / structure: Three horizontal strips. Top = clinical workflow (Patient → Triage → Consultation → Diagnosis → Treatment → Monitoring) rendered as a linear process diagram. Middle = radial diagram with a radiologist at center surrounded by MLLM support tasks. Bottom = radial diagram with an AI icon at center surrounded by clinical-integration challenges. Two radial compositions mirror each other visually — a deliberate parallel that frames "capabilities vs. challenges".

Whitespace & balance: Each strip is framed in a light background panel with its title on the left (Clinical Workflow / MLLM Support for Radiologist / Key Challenges for Clinical Integration) — the row-label placement anchors the reader and allows side-by-side reading without a separate key.

Typography (font size, weight, alignment): Row-label italics on the left are consistent. Radial labels (Visual Question Answer, Clinical Decision Support, etc.) use sentence case and are placed at consistent radial distances from center.

Emphasis (which elements are visually strongest, why): The two central icons (radiologist, AI chip) draw the eye first, making each radial panel's subject unmistakable. The triage/diagnosis/treatment icons in the top strip are sized uniformly so no single step is over-emphasized — correctly, because this is a generic workflow.

Color usage: Warm peach/cream for support, cool blue for challenges — a clean semantic contrast. Individual radial spokes are lightly tinted to differentiate themes within each group.

Weaknesses (if any — nothing is perfect): The radial metaphor collapses any ordering between spokes — a reader cannot tell which challenge is most pressing or which MLLM role is primary. Some icon glyphs (e.g., "Final Decision by Radiologist") are small and may not read clearly when printed at single-column width.

pipeline Exemplars

This directory will hold 3–5 hand-curated pipeline flow/figure exemplars. Use the extraction script to add one:

python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
    --pdf "/path/to/paper.pdf" \
    --page N \
    --type pipeline \
    --label LastnameYEAR_PIPELINE \
    --doi 10.xxxx/yyyy

See ../README.md for curation guidelines.

prisma Exemplars

This directory will hold 3–5 hand-curated prisma flow/figure exemplars. Use the extraction script to add one:

python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
    --pdf "/path/to/paper.pdf" \
    --page N \
    --type prisma \
    --label LastnameYEAR_PRISMA \
    --doi 10.xxxx/yyyy

See ../README.md for curation guidelines.

Exemplar Diagrams — Quality Anchors for the Critic Loop

This directory holds a small, hand-curated set of flow-diagram and figure examples from published papers that we consider high-quality. The Critic Loop references these as "visual structure first" anchors when reviewing newly generated figures.

Layout

exemplar_diagrams/
├── strobe/      # cohort / cross-sectional / case-control flow
├── stard/       # diagnostic-accuracy flow diagrams
├── consort/     # RCT participant flow
├── prisma/      # systematic review selection flow
├── pipeline/    # methods / algorithm flow diagrams
└── {other...}/  # future types (roc, forest, km, ...)

Each category directory can hold two kinds of files:

1. Review anchors (for the Critic Loop) — groups of three files per exemplar:

• {label}.png — rendered figure cropped from a published paper (≥300 DPI)
• {label}.meta.yaml — attribution metadata (source PDF, page, DOI, crop coords)
• {label}_why.md — 50–100 word note on why this figure is a good anchor

2. Generation templates (for generate_flow_diagram.R) — one set per category:

• template_input.yaml — minimal schema example showing all supported fields
• template_output.{pdf,png,_600.png} — rendered reference output for the template
• Render with Rscript ../../scripts/generate_flow_diagram.R --type <type> --config <dir>/template_input.yaml --out <dir>/template_output

How to add a new exemplar

python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
    --pdf "/path/to/paper.pdf" \
    --page 3 \
    --type stard \
    --label LastnameYEAR_STARD \
    --doi 10.1148/radiol.2017170371 \
    --crop 0.05,0.1,0.95,0.6

Then open the generated {label}_why.md and fill in the curator's note (50–100 words on hierarchy, whitespace, typography, emphasis, color).

Curator guidelines

• Source quality — prefer examples from Radiology, NEJM, Lancet, JAMA,

European Radiology, BMJ, Cochrane Reviews. Lower-tier sources only when they show a specifically good design pattern.

• One exemplar per design principle — do not add five near-identical

examples. Aim for 3–5 exemplars per category, each illustrating a different design strength.

• Crop tightly — remove surrounding caption and whitespace so the

exemplar is purely the diagram.

• No open-access conflict — avoid exemplars from paywalled figures

where fair-use for internal reference review is unclear. Prefer open-access or CC-licensed papers when possible.

Attribution

Exemplars are used under fair-use for internal quality review only. They are not redistributed as part of generated figures — the Critic Loop uses them read-only as anchors for feedback. The _meta.yaml sidecar records DOI and source for every exemplar.

stard Exemplars

This directory will hold 3–5 hand-curated stard flow/figure exemplars. Use the extraction script to add one:

python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
    --pdf "/path/to/paper.pdf" \
    --page N \
    --type stard \
    --label LastnameYEAR_STARD \
    --doi 10.xxxx/yyyy

See ../README.md for curation guidelines.

Exemplar anatomy — Bland–Altman agreement plot (two continuous methods)

A worked anatomy model for a Bland–Altman figure — the agreement counterpart to a method- comparison scatter. Complements the critic_rubrics/data_plot.md §C Bland–Altman checklist (this composes; the rubric scores). Synthetic — describes what each element must show and the errors to avoid; not an image to copy. Pairs with analyze-stats table-standards/table-types/agreement.md (the LoA / ICC reliability table).

Elements

• Difference (y) vs mean of the two methods (x) — y = (method A − method B), x = (A + B)/2.

Plotting the difference against one method (e.g., the reference) induces a spurious slope; the mean of the two is the correct abscissa.

• Bias line = the mean difference, drawn horizontally, with its value and 95% CI printed.
• 95% limits of agreement (LoA) = bias ± 1.96·SD of the differences, drawn as two horizontal

lines, with a confidence interval on each limit (the LoA are themselves estimates and are wide at small n) — show the CI as a footnote value or a shaded band around each LoA.

• The a-priori clinically acceptable difference band overlaid, so the reader can see at a glance

whether the LoA fall inside the margin that was defined before the analysis.

• Proportional-bias check: a regression of the difference on the mean; if the slope is non-zero

(the cloud fans out or tilts), state it and model the SD or log-transform rather than quoting a single constant LoA.

• % of points within the LoA annotated (≈95% expected) and scatter points not clipped at the

plot edges — outliers beyond the LoA are the most informative points and must remain visible.

• Units stated on both axes (the difference is in measurement units, not %), and n pairs given.

Discipline (what the figure must not do)

• It is not a correlation/regression plot — do not report Pearson r or R² as evidence of

agreement. High correlation is fully compatible with large systematic bias; correlation measures association along a line, not closeness to identity.

• Do not quote a single constant LoA when bias is proportional — if the differences widen with

magnitude (heteroscedasticity), constant ±1.96·SD limits are wrong across the range; log-transform or model the SD as a function of the mean.

• Do not omit the CI on the LoA — at small n the limits are imprecise, and an LoA that looks

inside the acceptability margin may not be once its upper CI is shown.

• Handle repeated measures correctly — with multiple pairs per subject, the naïve SD of all

differences understates variability; use a repeated-measures Bland–Altman (variance-components) method and report the number of replicates per subject.

• Clinical acceptability is a pre-specified judgement, not read off the plot after the fact —

state the margin and its source, and conclude agreement only if the LoA (with CI) fall inside it.

Common omission

• The CI on the limits of agreement, the proportional-bias check, and the **pre-defined

clinical-acceptability band** — the elements Bland–Altman figures most often drop, and the ones that decide whether two methods are interchangeable rather than merely correlated. Cross-reference critic_rubrics/data_plot.md §C (Bland–Altman) and analyze-stats table-standards/table-types/agreement.md.

Exemplar anatomy — calibration plot (risk-prediction model)

A worked anatomy model for a calibration figure — the probability counterpart to the ROC/PR discrimination plot. Complements the critic_rubrics/data_plot.md §C / §G calibration checks (this composes; the rubric scores). Synthetic — describes what each element must show and the errors to avoid; not an image to copy. Pairs with analyze-stats templates/dca_plot.R and the TRIPOD+AI / exemplar_plots/roc_pr.md discrimination side.

Elements

• Predicted probability (x) vs observed frequency (y), both 0–1, with the 45° ideal line.
• A smooth/flexible calibration curve (loess or restricted cubic spline) rather than only a

handful of binned points — binning into deciles hides shape and is sensitive to the cut-points.

• Calibration slope and intercept reported in the panel: slope < 1 signals overfitting

(extreme predictions too extreme); the intercept is calibration-in-the-large (mean predicted vs mean observed risk), and intercept ≠ 0 signals systematic over/under-prediction.

• A distribution of predicted risks (rug/histogram under the axis), so the reader sees where

the data actually live — calibration in a region with no patients is uninformative.

• On the validation/external set, not the development set; with a CI band on the curve.

Discipline (what the figure must not do)

• Do not present discrimination (AUROC) as evidence of calibration — a model can rank well yet

be systematically miscalibrated; both are required when a probability drives a decision.

• Do not rely on the Hosmer–Lemeshow test alone — it is low-powered, depends on arbitrary

grouping, and a non-significant p is not evidence of good calibration; show the curve + slope/ intercept.

• Do not extrapolate the curve into probability ranges with no observations (see the rug).
• If recalibration was applied, say so and show calibration after it on held-out data.
• Where a threshold/decision is proposed, pair calibration with a decision-curve (net-benefit)

analysis.

Common omission

• The slope/intercept, the predicted-risk distribution, and **calibration on the external

set** — the elements calibration figures most often drop, and the ones that decide whether the probabilities can be trusted at the bedside. Cross-reference critic_rubrics/data_plot.md §C/§G, the peer-review/references/exemplar_reviews/calibration_missing.md finding, and analyze-stats templates/dca_plot.R.

Exemplar anatomy — clinical timeline for a case report

A worked anatomy model for a CARE case-report timeline figure. This is a synthetic teaching model: it describes what the figure must show, not a layout to copy from a published report. Use it when a case report has more than two meaningful events or when the diagnostic reasoning depends on the order of symptoms, tests, treatment, and outcomes.

Elements

• Relative time axis — use Day 0, Postoperative day 3, Week 6, or Month 12 rather than

exact calendar dates unless exact dates are essential and approved for publication.

• Event lanes — separate the course into readable lanes such as symptoms/examination, diagnostic

tests, imaging/pathology, treatment/intervention, and outcome/follow-up. Avoid a single overloaded line with every event stacked on top of it.

• Index presentation marker — make the initial presentation or referral point visually clear so

readers can orient the pre-presentation history and post-intervention course.

• Diagnostic assessment markers — include the decisive test modality, key finding, and diagnostic

impression in a compact label. If imaging is central, pair the timeline with an annotated image panel rather than forcing all visual detail into the timeline.

• Intervention markers — show the intervention start, changes, dose/procedure/device details only

when they alter interpretation, and discontinuation or complication points.

• Follow-up endpoint — include the final follow-up interval and outcome. A timeline that ends at

discharge when the manuscript claims recovery at 3 months is incomplete.

• Uncertainty/negative findings — include only the negative tests that changed diagnostic

reasoning. Routine normal findings belong in the text or table, not the figure.

• Legend linkage — the legend should state that all labels are de-identified and relative to the

index presentation; define abbreviations and outcome scales.

Annotated imaging panel pairing

For imaging-heavy case reports, use a two-part figure when possible:

• Panel A: clinical timeline — concise event sequence and outcome.
• Panels B-D: representative images — modality/sequence, anatomical location, arrows or labels for

the key finding, and an image-level note that all identifiers are removed.

• No decorative anatomy icons unless they carry information. If an icon is used, it must clarify

anatomical location or treatment pathway and have a license source.

Discipline (what the figure must not do)

• Do not expose identifiers — no dates, accession numbers, institution names, patient initials,

faces, tattoos, embedded DICOM overlays, or geography-specific labels.

• Do not imply causality with arrow grammar — use sequence arrows for chronology, but avoid visual

wording that makes treatment look proven to cause the outcome unless the text supports that claim.

• Do not overpack the timeline — if more than 10-12 events are needed, split into lanes or move

secondary laboratory values to a table.

• Do not omit scale/units — laboratory trends need units and outcome scores need the named scale.
• Do not let the image panel become decorative — every arrow should correspond to a finding named

in the case presentation or legend.

Common omission

• The final follow-up endpoint, relative-time de-identification, and **diagnostic-reasoning

sequence**. These are the elements that make the figure satisfy CARE's timeline expectation rather than serving as a decorative chronology. Cross-reference write-paper/references/exemplar_case_report.md, write-paper/references/paper_types/case_report.md, and the CARE checklist in /check-reporting.

Exemplar anatomy — confusion matrix (classifier error structure)

A worked anatomy model for a confusion-matrix figure — the per-class error breakdown behind a single accuracy number. Complements the critic_rubrics/data_plot.md §C confusion matrix checklist (this composes; the rubric scores). Synthetic — describes what each element must show and the errors to avoid; not an image to copy. Pairs with exemplar_plots/roc_pr.md (the threshold-free discrimination side) and analyze-stats table-standards/table-types/diagnostic_accuracy.md.

Elements

• TP / FP / FN / TN laid out as a 2×2 grid (binary case) with explicit axis labels: one

axis Predicted (model), the other Actual / Reference (truth) — never leave the reader to guess which axis is which, and state the positive class.

• Raw counts in every cell, so totals and prevalence are recoverable; a percentage-only matrix

hides the n behind each rate.

• Row-normalized (recall / sensitivity) and column-normalized (precision / PPV) views shown

alongside the counts — recall normalizes over true class (rows), precision over predicted class (columns); the two answer different questions and must not be conflated.

• The operating threshold stated — a confusion matrix is a single point on the ROC/PR curve;

give the probability cut-off used and how it was chosen (and on which data, not the test set).

• Per-class metrics derivable and reported (sensitivity, specificity, PPV, NPV, F1) with their

CIs, rather than one global accuracy.

• Diagonal emphasized (heavier stroke or luminosity) only as a reading aid — correct predictions

on the diagonal, errors off it.

Discipline (what the figure must not do)

• Do not let a high overall accuracy stand in for performance — under class imbalance a

classifier that always predicts the majority class scores high accuracy while the minority class fails completely; the off-diagonal recall for the rare class is the load-bearing number, and a class-imbalance caveat belongs in the caption.

• Do not normalize ambiguously — label whether percentages are over rows (recall), columns

(precision), or the grand total; an unlabeled "%" cell is uninterpretable.

• Do not present the matrix as threshold-free — it is threshold-dependent; pair it with the

ROC/PR curve (roc_pr.md) so the reader sees the whole operating range, not one chosen point.

• Do not report the matrix on the data used to pick the threshold — fix the threshold on

derivation data and report the matrix on the held-out/test set.

Multi-class extension

• For K classes, show the K×K matrix with the same Predicted/Actual axes; report per-class

recall and precision plus a macro-average (unweighted over classes, so rare classes are not drowned out) alongside any micro/weighted average, and name which average each headline number is.

Common omission

• The dual row/column normalization (recall vs precision), the stated operating threshold,

and the class-imbalance caveat — the elements confusion-matrix figures most often drop, and the ones that stop a high accuracy from hiding a failing minority class. Cross-reference critic_rubrics/data_plot.md §C (confusion matrix), exemplar_plots/roc_pr.md, and analyze-stats table-standards/table-types/diagnostic_accuracy.md.

Exemplar anatomy — decision curve (net-benefit / DCA)

A worked anatomy model for a decision-curve (net-benefit) figure — the clinical-utility counterpart to the ROC/PR discrimination plot and the calibration probability plot. A model can discriminate and calibrate well yet still add no decision value over treating everyone or no one; the decision curve is what shows whether acting on the model helps across a clinically plausible range of thresholds. Complements critic_rubrics/data_plot.md §C/§G (this composes; the rubric scores) and pairs with analyze-stats references/templates/dca_plot.R and the analyze-stats table-standards/table-types/incremental_value.md added-value table. Synthetic — describes what each element must show and the errors to avoid; not an image to copy, no real citations.

Elements

• Threshold probability (x) vs net benefit (y). The x-axis is the risk threshold at which a

patient/clinician would opt for the action (treat, biopsy, admit); the y-axis is net benefit, in units of true positives per patient, already penalised for false positives at that threshold.

• The two reference strategies on every panel: treat-all (a sloping line that crosses zero

at the prevalence) and treat-none (the horizontal line at net benefit = 0). The model is useful only over the threshold range where its curve sits above both references.

• The model curve(s) across a stated, clinically justified threshold range (e.g. 5–40%),

not a single point — the whole point is to show utility across the plausible decision region, and to name where that region comes from.

• When models are compared, each model as its own curve on the same axes (and, if shown, the

same external data), so the reader sees over which thresholds one strategy dominates.

• The operating threshold the paper actually proposes, annotated on the curve, with the net

benefit there — tying the figure back to the deployment decision.

• Built on the validation/external data with the model calibrated (see below), at a single

stated horizon for time-to-event outcomes.

Discipline (what the figure must not do)

• Do not read net benefit as accuracy — it is true positives minus weighted false positives;

a curve only marginally above treat-all means little added utility even if AUROC looks strong.

• Do not omit the treat-all and treat-none references — a model curve alone is uninterpretable;

utility is defined relative to acting on everyone or no one.

• Do not show an uncalibrated model — net benefit depends on the predicted probabilities, so a

miscalibrated model gives a misleading curve; pair with calibration_plot.md and recalibrate first if needed.

• Do not extend the threshold range past where decisions are actually made, and do not let the

curve wander into thresholds with no patients (cross-reference the predicted-risk distribution).

• Do not quote a single "the model is better" threshold without showing the range; report the

interval over which the model dominates and name the proposed operating threshold.

• For time-to-event outcomes, state the horizon and use a censoring-aware net benefit; a naïve

complete-case DCA over a censored cohort is biased.

Common omission

• The treat-all/treat-none references, the justified threshold range (where the

probabilities come from clinically), and calibration before the curve — the elements decision curves most often drop, and the ones that decide whether the figure supports a real use-the-model claim rather than a discrimination claim. Cross-reference critic_rubrics/data_plot.md §C/§G, the peer-review/references/exemplar_reviews/calibration_missing.md finding, analyze-stats references/templates/dca_plot.R, and the added-value table standard analyze-stats references/table-standards/table-types/incremental_value.md.

Exemplar anatomy — meta-analysis forest plot

A worked anatomy model for a publication-grade pairwise meta-analysis forest plot, complementing the critic_rubrics/data_plot.md §C forest checklist (this shows the full composition; the rubric scores a draft against it). Synthetic — describes what each element must show and the errors to avoid; not an image to copy. Pairs with analyze-stats templates/forest_plot.py / meta_analysis.R.

Elements (top to bottom)

• Per-study row: study label (author year), the effect estimate as a **square sized by

weight, and its 95% CI** as a horizontal line; the numeric estimate (95% CI) in a right column. Weight (%) shown numerically, not only by square size.

• Pooled diamond: the random-effects summary, its width = the summary 95% CI. State the

model (e.g., DerSimonian–Laird or REML random-effects) in the caption.

• Prediction interval: show it (a bar through the diamond) whenever k is sufficient — it

conveys where a new study's true (study-specific) effect would likely fall, which the summary CI (a confidence interval for the pooled mean) does not. Its absence is the single most common forest-plot omission.

• Heterogeneity line: report I², τ² (or τ), and Cochran's Q with its p beneath the

diamond — τ² is the actual between-study variance and must not be left implicit.

• Reference line at the null (OR/RR/HR = 1, or 0 for mean differences); a log scale for

ratio measures so CIs are symmetric.

• Axis: framed to include all CIs without wasted whitespace; label the effect measure and

which direction favours which arm.

Discipline (what the figure must not do)

• Do not pool when pooling is not defensible: when heterogeneity is extreme *and

unexplained* (a high I² with a large τ² and no subgroup/meta-regression that accounts for it), or k is very small, a single summary can be clinically and statistically misleading — then present studies without a summary diamond, or restrict to a justified subgroup, rather than showing a precise diamond that implies an agreement the studies do not have. (I² is a guide, not an automatic cut-off — judge it with τ² and whether the heterogeneity is explained.)

• Subgroups: plot each subgroup with its own diamond and a test for subgroup differences;

do not narrate subgroup effects that are not shown as plotted strata.

• Small-study effects: a funnel plot + Egger's test belong with the forest **only when

k ≥ 10**; below that, say tests are underpowered rather than over-interpreting asymmetry.

• Certainty: where GRADE is used, a certainty column (or caption note) keeps a tight CI from

being read as strong evidence when risk of bias/imprecision is high.

Common omission

• A prediction interval and an explicit τ², plus an honest **no-pool / restrict

decision under extreme heterogeneity** — the elements forest plots most often skip, and the ones that turn a precise-looking diamond into an over-statement of agreement. Cross-reference critic_rubrics/data_plot.md §C (forest) and the SR/MA reporting items via /check-reporting (PRISMA).

Exemplar anatomy — annotated multimodality imaging panel (case report / series)

A worked anatomy model for the composite imaging figure that carries a radiology case report or series — the figure where the diagnosis lives. This is a synthetic teaching model describing what the panel must show, not a layout to copy. Use it when the teaching point is an imaging finding, a cross-modality discordance, or a treatment response. Complements clinical_timeline.md (which carries chronology); this file carries the images themselves.

Elements

• Panel grid with explicit labels — one sub-panel per modality, sequence, or timepoint (e.g.,

mammography / ultrasound / FDG PET-CT; or T2 / FLAIR / DWI / post-contrast). Letter each sub-panel (A, B, C…) and state the modality/sequence and plane in the caption, not only the image.

• Arrow or marker to the key finding in every sub-panel — the reader must see what to look at.

An unannotated image is a decoration, not evidence.

• Quantitative labels where a number is the point — lesion size, SUVmax, BI-RADS/standardized

category, signal characteristics, degree of stenosis. These anchor the description in the text.

• Same-lesion correspondence across panels — when showing discordance (e.g., visible on one

modality, occult on another) or response (pre- vs post-treatment), keep the same lesion/orientation so the comparison is read at a glance; mark the same anatomical landmark in each.

• Modality-appropriate orientation and scale — laterality labels (L/R), a scale where size is

load-bearing, and consistent windowing across compared panels.

• Histopathology/immunostain sub-panel when origin hinges on it — stain name and magnification in

the caption (e.g., the EBER/IHC panel that settles a mimic).

• Caption that states de-identification and defines every abbreviation/scale used in the labels.

Discipline (what the figure must not do)

• Do not expose identifiers — strip dates, accession numbers, institution banners, patient

initials, faces, and embedded DICOM overlays before export.

• Do not show unannotated images — every sub-panel needs an arrow/label tying it to a finding

named in the case presentation.

• Do not imply causality or response without correspondence — a "before/after" pair must be the

same lesion/plane; mismatched views overstate the change.

• Do not omit the quantitative anchor when the teaching point is a number (an "occult on PET"

claim needs the SUVmax; a "stenosis" needs the degree or velocity).

• Do not overcrowd — split into more sub-panels rather than stacking arrows on one image.

Common omission

• Cross-modality / cross-timepoint correspondence and the quantitative label. A case whose

lesson is discordance or response fails if the panels are not the same lesion or the decisive number is missing. Cross-reference write-paper/references/exemplar_case_report.md (diagnostic-assessment and adverse-event/mimic subtypes), clinical_timeline.md for the chronology figure, and the CARE checklist in /check-reporting.

Exemplar anatomy — Kaplan–Meier survival curve

A worked anatomy model for a publication-grade Kaplan–Meier figure, completing the figure side of the survival pair (the table side is analyze-stats/.../table-types/survival_results.md). Synthetic — describes what each element must show and the errors to avoid; not an image to copy. Pairs with analyze-stats templates/survival_analysis.py / survival (R).

Elements

• Step curves, one per group, visually distinguishable by line style as well as colour

(colourblind-safe; do not rely on colour alone).

• Number-at-risk table aligned under the x-axis at each labelled time — the single most

important KM element; without it a reader cannot judge how much of the tail is real.

• Censoring marks (ticks on the curve at censoring times), so attrition is visible.
• Confidence band around each curve, or at least the median's CI — a curve without

uncertainty overstates precision in the sparse tail. Say which kind: a pointwise band covers each time separately and does not give simultaneous coverage over the whole curve; a simultaneous (e.g., Hall–Wellner / equal-precision) band does.

• Group contrast annotated: the log-rank p and/or the HR (95% CI) with its model,

and median survival per group with 95% CI (or "not reached").

• Axes: y from 0 to 1 (or 0–100%) labelled with the estimand (overall survival, PFS, …);

x labelled with the time unit; a reference line is optional.

Discipline (what the figure must not do)

• Do not extend the x-axis past where the risk set is thin. Truncate at (or annotate) the

point where estimation stops being supported — judge this by the number at risk and the remaining events, and by where the CI widens sharply (e.g., once n-at-risk falls below a small fraction of baseline) — the far tail is driven by a few patients and the steps are noise.

• Do not read a survival probability off a horizon beyond the data; if a fixed-time estimate

(e.g., 5-year survival) is quoted, the number at risk at that time must support it.

• Do not omit censoring — heavy early censoring with a flat curve can masquerade as good

survival.

• For competing risks, a KM of one cause overestimates its incidence — use a cumulative

incidence function (CIF) instead, and say so.

• If proportional hazards is violated, the curves crossing is itself the message; pair with an

RMST or a time-window statement rather than a single HR (see the survival table-type).

Common omission

• The number-at-risk table and censoring marks — the two elements KM figures most often

drop, and the two a reviewer checks first, because both govern whether the tail can be believed. Cross-reference critic_rubrics/data_plot.md §C (KM) and the survival table-type in analyze-stats/references/table-standards/table-types/survival_results.md.

Results

The analytic cohort comprised 998 participants.

Figure Legends

Figure 1. STROBE flow diagram. Of n = 1,284 assessed for eligibility, n = 286 were excluded, leaving an analytic cohort of n = 998.

References

Figure Legends

Figure 1. STROBE flow diagram. Of n = 1,284 assessed for eligibility, n = 286 were excluded, leaving an analytic cohort of n = 1,150.