siyunhao2025-beep/huaweibei-cool/academic-figure

Academic Figure Skill Hub

Academic Figure Skill generates publication-grade scientific figures for Nature/Cell/Science family journals. Every figure starts from the scientific question, not from a template.

Design Principles

1. One figure, one core message. CNS reviewers skim fast. A figure must convey its main conclusion in 3 seconds. Remove gridlines, borders, and legend entries that dilute the core message. Default to minimal, not maximal.

2. Semantic color richness > arbitrary color abundance. Default palettes (matplotlib tab10, ggplot2 hue_pal, Excel colors) signal "not designed" instantly. Use 2-4 semantic main colors + 1 accent within one Figure, while varying justified palette roles and figure families across a paper. See references/color-palettes.md.

3. Design for print, not screen. Journal column widths are fixed (89 mm single, 183 mm double). Set figure dimensions at creation time — never scale down post-render.

4. Vector first, raster as fallback. Line art, scatter plots, bar charts → PDF/SVG/EPS. Only true raster content (heatmap color blocks, micrographs) should use TIFF/PNG at ≥300 dpi.

Complete Workflow

Follow this closed loop for every request. Never skip steps. Never assume the user's question.

User request received
       │
       ▼
  Step -1: Understand the Task ←── DISPATCH FIRST. If the user gave data but
       │                         didn't say what they want to learn, ASK.
       ▼
  Step 0: Parse Data, Match to Task ←── Data parsing is directed by the
       │                                question, not by a template.
       ▼
  Step 1: Recommend & Justify ←── "To answer your question, you need these
       │                         N panels. Here's why." N depends on the
       ▼                         question, not on a fixed number.
  User Confirms ──→ No → Refine recommendation
       │
       ▼ Yes
  Step 2: Runtime & Environment ←── Detect Python + R availability.
       │                            Install or configure if missing.
       ▼
  Step 3: Style Baseline Injection ←── typography + color + export blocks.
       │                               Copied VERBATIM into every script.
       ▼
  Step 4: Production Asset Scan ←── ls assets/figures/. For EVERY panel in
       │                            the plan, check matching scripts.
       ▼
  Step 5: Generate ←── COPY-FIRST for matching scripts → native run.
       │              No match → cross-type inherit.
       ▼
  Step 5.5: Validate Data ←── Data sanity checks BEFORE rendering.
       │
       ▼
  Step 6: QA Protocol ←── 4-pass QA (AP-0..AP-7, CL-1..CL-7,
       │                  VI-1..VI-6, VV-1..VV-5). Fix → re-render.
       ▼
  Step 7: Deliver ←── Vector PDF master + 300dpi PNG preview
                      + QA report + statistics report

Step -1: Understand the Task — DISPATCH FIRST

Before reading a single data file, understand what the user is trying to learn. A dataset without a question is a spreadsheet, not a figure. The entire visualization plan flows from this question.

Classify the request into one of:

If the user gave data without a question, the default response is a question, not a figure.

Step 0: Classify & Parse

Step 0a — Classify the figure archetype FIRST. Before parsing data, classify the figure into one of four archetypes. This determines layout strategy.

If unsure, default to `asymmetric_mixed` — it produces the Nature-style look of one dominant panel + subordinate evidence panels. Pure symmetric grids are rare in top-tier journals outside of supplement.

Pass the archetype to compose_figure(archetype=...). The engine auto-detects which panel is the hero and applies asymmetric layout when the archetype is not quantitative_grid or symmetric.

Step 0b — Parse data. Once the archetype is classified, read and analyze the data — but only the aspects relevant to the question.

1. Parse structure: Load the data. Count rows, columns. Classify each column (continuous / categorical / group label / identifier).

DATA INTEGRITY RULE — NON-NEGOTIABLE:

• Use ALL user-provided data. Never downsample, never select "representative" rows, never pick "a few columns to keep it simple", never np.random.choice(df, 12) when the user gave 1200 rows. The user's data IS the ground truth. Reducing it is fabricating evidence.
• If rendering performance is a concern (e.g. scatter plot with >50K points), use rasterized=True or vector-friendly density representations. Never subsample to solve a rendering problem.
• If a production script expects a different data shape than the user provided (e.g. script needs real_value.csv + pred_value.csv but user has Pheno1-Pheno8), do NOT silently adapt by picking two columns. Inform the user: "This script expects paired X/Y data. Your data has N columns. Which two should I use as X and Y?" Wait for confirmation before proceeding.
• If you drop any rows or columns for ANY reason, state exactly how many were dropped, why, and get user acknowledgment in the QA report. Silent data loss is the #2 most serious bug in this skill.

1. Run question-directed analysis: The question determines what to compute.

• "Does X differ between groups?" → Compute group means, between/within variance, pairwise tests
• "What drives Y?" → Compute correlation matrix, PCA, feature importance
• "Are these two variables related?" → Compute correlation, fit line, check residuals
• "What's the distribution?" → Compute summary stats, test normality, detect outliers

1. Do NOT run generic analysis. If the question is about group differences, don't report the full correlation matrix. If the question is about correlation, don't compute group means for every possible partition. Data parsing serves the question, not the other way around.

Step 1: Recommend Figures & Justify

Based on the question and the data morphology, propose a visualization plan. For each panel, state:

1. What question does this panel answer? — One sentence per panel.
2. Why this figure type? — Justify the choice based on data characteristics, not habit.
3. How many panels? — Determined by the number of distinct questions, not by a template. Two questions → two panels. Six questions → six panels. No filler panels.

The recommendation must follow this structure:

Visualization Plan
 
Scientific goal: [one sentence — what the user wants to learn]
 
| Panel | Figure type | Answers | Data basis |
|-------|------------|---------|------------|
| (a)   | [type]     | [question] | [e.g. Pheno1-6 all r>0.9 → heatmap] |
| (b)   | [type]     | [question] | [e.g. PC1=92% → PCA with group coloring] |
| ...   | ...        | ...     | ... |
 
Total: N panels. Layout: [M×N]. Journal: [target].

Re-evaluate after user feedback. If the user says "also show X" or "don't need Y", update the plan and re-present. Only proceed after explicit confirmation.

Step 2: Runtime & Environment

After the plan is confirmed, before generating any code, verify the execution environment.

1. Detect available runtimes:

python --version 2>/dev/null || python3 --version 2>/dev/null
Rscript --version 2>/dev/null || ls "/c/Program Files/R/"*/bin/Rscript.exe 2>/dev/null

Store as PYTHON_AVAILABLE, R_AVAILABLE, R_PATH.

1. Match runtimes to the plan: For each panel in the confirmed plan:

• If a production script exists (will be checked in Step 3) → the script's language must have a runtime
• If no production script exists → generate in Python (default) or R (user preference)

1. Handle missing runtimes:

• R panel requested but R not found → Tell user: "Panel (c) needs R with ComplexHeatmap. Install R or I'll use Python fallback (lower quality)."
• Python panel requested but Python not found → Tell user: "Python not found. Install Python 3.9+."
• Missing R packages → install.packages(...) command provided
• Missing Python packages → pip install ... command provided

Do not silently fall back. The user decides whether to install the missing runtime or accept lower quality.

Step 3: Style Baseline Injection (ALWAYS FIRST)

Load these three files and copy their "COPY VERBATIM" code blocks into the script — in order, at the very top, before any panel logic:

1. references/typography.md — rcParams/theme block. Fonts, spines, ticks, legend defaults.
2. references/color-palettes.md — PALETTE constants. All color variables.
3. references/export-specs.md — font embedding + save function.

Also read references/journal-specs.md for target dimensions (89mm single / 183mm double).

Step 4: Production Asset Scan (EVERY panel)

Run AFTER plan confirmation, BEFORE code generation. For EVERY panel in the confirmed plan:

1. First, read `references/directory-map.md`. This table maps user language (Chinese + English) to exact assets/figures/<dir>/ paths. Find the user's description in the "Keywords" column → use the exact directory path. This prevents the #2 recurring bug: "柱状图" matching the wrong bar sub-directory.
2. Verify with ls assets/figures/<matched-dir>/ that the directory exists and has scripts.
3. Check the matching directory for production scripts (.py, .R, .r).
4. For each match, check if the script's language runtime is available (from Step 2).
5. Verify script can work with user data. Read the script. Identify the script's "data entry points" — which variables receive external data (column names, data frames, file paths). Map them to the user's data columns. If the mapping exists but columns differ (e.g. script expects length/number_of_cds but user has Pheno1/Pheno2), mark as "visual adapt" — the script's visual system is preserved, only data mapping changes. Only mark as "incompatible" when the data STRUCTURE fundamentally differs (e.g. script expects paired X/Y CSV files but user has a single wide table).
6. Fallback: Only if directory-map.md has no matching entry, fall back to scanning ls assets/figures/ and matching directory names.

Decision per panel: