Academic Figure Skill

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

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

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

Panel type matched in assets/figures/<type>/
    │
    ├── Script exists + runtime available + data STRUCTURE matches → COPY-FIRST.
    │   1. Copy the ENTIRE script file to work_dir/<panel>_production.<ext>
    │   2. Find the data-loading line, replace ONLY the data path
    │   3. Execute: subprocess.run([python/r_bin, script])
    │   4. If FAIL: log reason → downgrade to VISUAL ADAPT with notice
    │   5. If OK: load rendered PNG via Image.open() in composition
    │   Panel quality = PRODUCTION. NEVER write a drawing function for this panel.
    │
    ├── Script exists + data COLUMNS differ but STRUCTURE matches → VISUAL ADAPT (NEW).
    │   The script's visual system (layout, coords, colormap, annotations, inset
    │   positioning, statistical overlays) is PRESERVED. Only the data mapping changes.
    │
    │   VISUAL ADAPT protocol — PRESERVES production script's visual system:
    │
    │   **Step 0: SEMANTIC MATCH CHECK (NEW — run BEFORE column mapping).**
    │   Open the production script's companion PNG. Answer:
    │   - What does this script actually PRODUCE? (scatter with marginal density?
    │     grouped KDE? 2D kernel density contour? ridgeplot? violin?)
    │   - What does the USER want? (from their request: "边际密度图", "核密度图",
    │     "分布图", "density", "KDE", etc.)
    │   - Are they semantically compatible? (1D vs 1D? 2D vs 2D? same number of
    │     data dimensions?)
    │
    │   **If YES → Proceed to Step 1 (column mapping).**
    │   The script produces what the user wants. Column names differ but the
    │   visual system (layout, axes, transformations) can be preserved.
    │
    │   **If NO → STOP. Do not VISUAL ADAPT.**
    │   Column mapping cannot fix a semantic mismatch. A JointGrid 2D scatter
    │   script cannot produce a 1D marginal density plot no matter how you map
    │   columns. Two cases:
    │   - User wants 1D density of multiple variables → cross-type inherit from
    │     Ridge (density fill + bandwidth) or KDE/Density (distribution pattern)
    │   - User wants 2D scatter density → find a semantically matching 2D script
    │
    │   1. Identify the script's data entry points:
    │      - What column names does it reference? (e.g. "length", "number_of_cds")
    │      - What grouping variable? (e.g. "type", "Group")
    │      - What filtering columns? (e.g. "is_drep95")
    │   2. Map to user's data:
    │      - Script column X → User column ____ (choose most semantically similar)
    │      - Script column Y → User column ____
    │      - Script grouping col → User column ____ (or None if user has no groups)
    │   3. PRESENT THE MAPPING TO THE USER for confirmation.
    │   4. **Data range compatibility check (NEW):** Before copying the script, verify
    │      that the user's data values are compatible with the script's mathematical
    │      operations. Specifically check:
    │      - Does the script use log-scale axes? → User data must have NO values ≤ 0
    │      - Does the script normalize to [0,1]? → User data must have finite range
    │      - Does the script use sqrt/division? → User data must be non-negative
    │      - Does the script bin continuous data? → User data must have sufficient range
    │
    │      If ANY check fails, identify which visual elements must be adapted:
    │      - Log scale with negative values → drop log transform, keep linear axes
    │      - Normalization with zero range → skip normalization, use raw values
    │      - Division by zero risk → add epsilon guard
    │      Tell the user which transforms were dropped and why.
    │   5. Copy the script. Modify ONLY:
    │      - Column name references (search-replace old col name → user col name)
    │      - Grouping column mapping (or set group=None if none)
    │      - Mathematical transforms that conflict with data range (from step 4)
    │      - Data path
    │      - NEVER modify: layout structure, color palettes, annotation logic,
    │        figure dimensions, export parameters
    │   6. Execute the adapted script. Verify output PNG renders.
    │   7. If execution fails: log reason → downgrade to PARAM INHERIT with notice
    │   Panel quality = PRODUCTION VISUAL SYSTEM. The layout and aesthetics are
    │   from the production script; only the data source changed.
    │
    ├── Script exists + data STRUCTURE incompatible → CROSS-TYPE INHERIT + INFORM.
    │   Tell user: "[dir] has scripts but fundamentally different data structure.
    │   Using cross-type inheritance. Visual quality will be lower."
    │
    ├── Script exists + runtime NOT available → EXTRACT PARAMETERS.
    │   Read the script's FULL content. Open its companion PNG.
    │   Extract Class A/B/C parameters. Cross-type inherit.
    │   Inform user of the quality tradeoff.
    │
    └── No script exists → CROSS-TYPE INHERIT.
        Borrow from similar figure type in the borrowing table below.

Requested type     Borrow from          What transfers
─────────────────────────────────────────────────────
RDA                PCA                  scatter point size, alpha, ellipse style
Radar              Bar                  color palette ratio, legend style
KDE / Density      Ridge                alpha fill, line color, bandwidth factor
UpSet              Confusion Matrix     fill color, edge color, font size
Single-cell traj.  PCA                  scatter point size, alpha, colormap
Forest             Bar                  line width, marker size, color logic
Sankey             (use own if exists)  node color palette, flow alpha
Heatmap            CorrHeatmap          colormap, colorbar settings
Correlation Scatter Scatter (basic)     point size, alpha, regression line style