Make Figures

Make-Figures Skill

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), ask the user, in their language, whether the data contains patient identifiers (names, national ID / RRN, contact details, etc.) and, if so, to 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 — read it before generating any figure (journal dimensions, DPI, file formats, palettes, font sizes, panel layouts, caption format).
• Figure style: ${CLAUDE_SKILL_DIR}/../analyze-stats/references/style/figure_style.mplstyle

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

Publisher pages set the floor; a journal's own guide can be stricter (JACC is an Elsevier journal). Check the target journal's guide as well as its publisher's.

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.

Even when AI images are allowed, experienced reviewers recognise AI-generated illustrations (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.

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.

AI Image Generation (Optional)

AI illustration is a supplementary option: every figure and visual abstract can be completed without an API key. If GEMINI_API_KEY is set, generate_image.py can generate illustrations (procedural schematics, anatomical illustrations), subject to the policy table and hard rule above:

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

If GEMINI_API_KEY is not set, use ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md.

Visual Abstract / Graphical Abstract

European Radiology made graphical abstracts mandatory for all Original Articles from first revision (Jan 2025); other journals encourage or accept them (status list in template_guide.md). Check the target journal profile (write-paper/references/journal_profiles/) for its 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):
   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 medsci_default \
     --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: one page, landscape (16:9) or per the journal template; three sections (study question → key method → main result); the study's actual figures rather than generic graphics; minimal text; no decorative clip-art.

Available Templates

Using a journal's own template. We do not redistribute journals' templates (e.g., European Radiology's EURA-GA-Jan2025.pptx): download it and pass its absolute path:

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --template /absolute/path/to/EURA-GA-Jan2025.pptx  ...

--template takes an absolute path to any .pptx. The script locates the fields by their text content rather than by shape name, so a journal's own template works unmodified. If the path does not exist it falls back to medsci_default.pptx.

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

Central Illustration vs Visual Abstract

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 (CI) with every Original Article. A CI is not a Visual Abstract: it conveys one key finding and contains no methods. Before making one, read ${CLAUDE_SKILL_DIR}/references/jacc_central_illustration_principles.md (CI vs VA table, the five Fuster-Mann rules, layout and validation thresholds).

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 criteria / exclusion criteria / 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. Submit only the content figure + citation: JACC editorial applies the red border and blue "CENTRAL ILLUSTRATION:" header after acceptance.

Workflow

Any reference in a caption, legend or illustration needs a DOI or PMID confirmed via /search-lit; mark one you cannot confirm [UNVERIFIED - NEEDS MANUAL CHECK]. Mark an unconfirmed clinical definition, criterion or guideline claim [VERIFY] and ask — the submission gates block on both.

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). 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 — 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 (infer what the context already gives, and confirm before proceeding):

1. Figure type — 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

Step 2: Configure

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

Step 3: Generate

Use Python (matplotlib/seaborn, with specialized libraries as needed). Compose each data plot from its anatomy model in ${CLAUDE_SKILL_DIR}/references/exemplar_plots/ (index in its README.md); for box/violin, bar and heatmap figures follow the per-type conventions in figure_specs.md. Flow diagrams never use matplotlib — see the Tool Selection Guide.

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)

Never fabricate data points. If sample data is needed for a template demo, label it "example data". 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.

Step 4: Review

Present the figure to the user (layout, labels and annotations, colors/sizing/emphasis) and iterate until the user approves.

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

Before Step 5 Export, run two stages — deterministic quantitative checks, then your own qualitative review — to decide 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 \
    --out figures/fig1_stard.critique.json

--source-text is optional (expected strings for OCR coverage). The JSON report covers DPI and physical width vs. the journal spec, the dominant-color breakdown and out-of-Wong-palette fraction, and OCR word count, minimum text height, and source-word coverage. When the image carries no DPI metadata, the DPI check uses the resolution at the spec width (width_px / --spec-width-in). A check that cannot run (physical width without DPI metadata, OCR without pytesseract) is listed under not_run and the summary reads INCOMPLETE, never PASS; --strict exits 3 on INCOMPLETE.

Stage 2: Qualitative review

1. Use the Read tool to load the generated PNG.
2. Read the corresponding rubric file (sections A–G in each):
   • Flow diagrams: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/flow_diagram.md
   • Data plots: ${CLAUDE_SKILL_DIR}/references/critic_rubrics/data_plot.md
   • For PRISMA / CONSORT / STARD / STROBE, also read ${CLAUDE_SKILL_DIR}/references/flow_diagram_lessons.md (official-template fidelity, PDF export via VML fallback, docx XML escape, sequential placeholder mapping, frozen-version sync with the manuscript).
   • For AI-extension guidelines or pipeline figures, also check against the reporting_guideline_figure_map.md row / pipeline_concepts_medical_ai.md loaded in Step 1.
3. Read the _why.md design notes in ${CLAUDE_SKILL_DIR}/references/exemplar_diagrams/{type}/ — hierarchy, whitespace, typography, emphasis, colour. They are the anchors. Where a rendered exemplar is bundled (template_output*.png), Read 1–2 of those too. Figures cropped from published papers are not shipped (see that directory's README); a user's own local exemplars can be used instead. For a non-flow data plot, 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 (node/label 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 (flow-diagram config/R script 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 Study-Type Figure Sets) 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 to analysis/figures/ (analysis/figures/*.pdf, analysis/figures/*.png):

• 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) — produce it with export_portal_tiff.py, not a raw magick ... output.tiff: that keeps the alpha channel (transparent regions print black on many production pipelines) and stays uncompressed (a 600-dpi RGBA TIFF blows past a portal's 25 MB cap). The script white-flattens RGBA→RGB, LZW-compresses, and verifies the result is pixel-identical to that flatten. Use it when a portal accepts only .tiff/.jpeg/.eps (Springer Nature SNAPP) or caps figure size (JACC: Asia):

  python3 ${CLAUDE_SKILL_DIR}/scripts/export_portal_tiff.py --in figure.png --out figure.tiff --max-mb 25
  # exit 1 if still over the cap

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.

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).