Plotting SOP

Plotting SOP — Scientific Plotting Standard Operating Procedure

When to Read This Skill

Read this skill when the user asks to:

Draw, plot, or visualize any figure or diagram
Create charts for a paper (bar, line, scatter, heatmap, radar, etc.)
Draw flowcharts, architecture diagrams, or concept maps
Generate figures during academic writing (called from writing-sop Phase 2)
Convert data into visual representations

§1 Environment Detection (run once per session)

Before generating any figure, MUST check available capabilities. Run these checks silently (do not show output to user unless something fails):

Check 1: python3 -c "import matplotlib; print('matplotlib', matplotlib.__version__)"
Check 2: python3 -c "import seaborn; print('seaborn', seaborn.__version__)"
Check 3: which mmdc 2>/dev/null || npx --yes @mermaid-js/mermaid-cli mmdc --version 2>/dev/null
Check 4: python3 -c "import cairosvg; print('cairosvg OK')" 2>/dev/null

Record results in session memory. Do NOT repeat these checks for subsequent figures.

If matplotlib is missing (common on native macOS/WSL2 installs):

Tell user: "Python scientific plotting library is not installed. Do you allow me to run the installation script? (about 30 seconds)"
If user agrees: bash scripts/setup-plotting-env.sh
If setup script not found: pip install --user matplotlib seaborn numpy pandas
If user declines: skip Python Engine, use Mermaid or AI Image instead

If mmdc is missing: This is normal. Use npx --yes @mermaid-js/mermaid-cli mmdc as fallback. If npx also fails: save .mmd file and tell user to paste at https://mermaid.live

§2 Engine Selection Decision Tree

MUST follow this decision tree for every figure request. Do NOT skip steps.

User requests a figure
  │
  ├─ 1. Is it DATA VISUALIZATION (charts with numbers/statistics)?
  │    YES → §4 Python Engine
  │    Examples: bar chart, line plot, scatter, heatmap, violin, radar, histogram, box plot
  │
  ├─ 2. Is it a SIMPLE STRUCTURED DIAGRAM (≤15 nodes AND aesthetics not critical)?
  │    YES → §5 Mermaid Engine
  │    Examples: simple flowchart, sequence diagram, class diagram, Gantt chart
  │
  ├─ 3. Is it a COMPLEX diagram (>15 nodes OR requires visual polish)?
  │    (architecture diagram, research methodology flow, concept map,
  │     multi-layer system diagram, publication-quality illustration)
  │
  │    → Is NanoBanana/OpenRouter configured?
  │        YES → §6 AI Image Engine (NanoBanana)
  │        NO  → Recommend NanoBanana to user (see §3)
  │              → User provides API key? → §6 AI Image Engine
  │              → User declines?
  │                  → WARN: "本地引擎生成复杂流程图的质量有限，可能需要手动调整。"
  │                  → Fall back to §5 Mermaid Engine (best effort)
  │
  └─ 4. Is it a CUSTOM VECTOR graphic (geometric shapes, coordinate annotations)?
       YES → §7 SVG Engine

§3 NanoBanana Configuration Guide

NanoBanana provides access to Gemini's native image generation through OpenRouter. It is the only reliable path for complex, publication-quality academic diagrams because it generates images directly (pixel-level), bypassing code generation entirely.

Why recommend NanoBanana

LLM-generated Mermaid/Python code for complex diagrams frequently has syntax errors
Even when correct, code-rendered diagrams look mechanical and unprofessional
Gemini image generation produces visually polished, publication-ready figures
Low-IQ models benefit most: the API quality is independent of the local model's coding ability

Configuration

User needs to provide an OpenRouter API Key. Store in MEMORY.md under ## Global > ### Environment:

NanoBanana: configured
OpenRouter API Key: [stored in environment, not in memory]

Recommended model: google/gemini-2.5-flash-preview-image-generation Alternative model: google/gemini-2.5-pro-preview-image-generation API endpoint: https://openrouter.ai/api/v1/chat/completions

How to tell the user

When the user requests a complex diagram and NanoBanana is not configured:

"For this type of complex academic chart, it is recommended to use NanoBanana (based on Gemini image generation) for the best results. You only need to provide an OpenRouter API Key (https://openrouter.ai/settings/keys）。 If you do not want to configure it, I can also try generating it using local tools (Mermaid/Python), but the quality may be limited."

§4 Python Engine — Data Visualization

For charts based on numerical data: bar, line, scatter, heatmap, violin, radar, box, histogram, pie, area, etc.

Output Path Resolution (MUST set before generating code)

Set output_path per §9 naming convention:

output_path = "outputs/figures/{topic}-fig{N}.png"

Example: outputs/figures/model-comparison-fig1.png

Code Template (MUST follow this structure)

The generated Python code MUST include all of the following elements. Low-IQ models: copy this template exactly, then fill in the plotting section.

import matplotlib
matplotlib.use('Agg')  # Non-interactive backend — MUST be before pyplot import
import matplotlib.pyplot as plt
import numpy as np

# ── Academic style settings ──────────────────────────────────
plt.rcParams.update({
    'font.family': 'sans-serif',
    'font.size': 12,
    'figure.dpi': 300,
    'axes.linewidth': 1.2,
    'axes.grid': True,
    'grid.alpha': 0.3,
    'legend.framealpha': 0.9,
})

fig, ax = plt.subplots(figsize=(10, 6))

# ── [YOUR PLOTTING CODE HERE] ───────────────────────────────
# Generate reasonable example data if user did not provide actual data.
# If using example data, add text annotation: "Example Data" in bottom-right.

# ── Labels and title (ALL ENGLISH) ──────────────────────────
ax.set_xlabel('X Label', fontsize=13)
ax.set_ylabel('Y Label', fontsize=13)
ax.set_title('Chart Title', fontsize=14, fontweight='bold')

# ── Save ─────────────────────────────────────────────────────
plt.tight_layout()
plt.savefig('{output_path}', format='png', dpi=300, bbox_inches='tight')
plt.close()
print('OK')

Execution Protocol

Generate code following the template above
Save code to temp file: system.run with inline Python or write to /tmp/rc_plot_{hash}.py
Execute: python3 /tmp/rc_plot_{hash}.py
Check result:
- Exit code 0 AND "OK" in stdout AND output file exists → SUCCESS
- Otherwise → FAILURE → enter ReAct loop

ReAct Self-Correction (max 3 attempts)

If execution fails:

Attempt 2-3: Inject the previous code and error into your next generation:

## Previous attempt FAILED. Fix the code.

### Previous code:
[paste the code that failed]

### Error output:
[paste stderr, truncated to 500 chars]

### Fix instructions:
- Analyze the error carefully
- Fix syntax errors, indentation, missing imports
- Ensure matplotlib.use('Agg') is BEFORE pyplot import
- Ensure savefig path is correct: {output_path}
- Do NOT use libraries that are not installed (stick to matplotlib, numpy, pandas, seaborn)

If all 3 attempts fail → inform user: "Python plotting failed. Please check the data format or simplify the chart requirements."

Color Palettes (academic standard)

Use case	Palette	Code
Categorical (≤10)	tab10	`plt.cm.tab10`
Categorical (≤8)	Set2	`plt.cm.Set2`
Sequential	viridis	`cmap='viridis'`
Diverging	RdYlBu	`cmap='RdYlBu'`
Colorblind-safe	Paired	`plt.cm.Paired`

NEVER use red-green only contrast. Always use colorblind-safe palettes.

Chart Type Quick Reference

User says	Chart type	Key code
bar chart/bar chart	Grouped bar	`ax.bar(x, y)`
line chart/line chart	Line plot	`ax.plot(x, y)`
scatter/scatter	Scatter	`ax.scatter(x, y)`
heatmap/heatmap	Heatmap	`import seaborn as sns; sns.heatmap(data)`
box plot/box plot	Box	`ax.boxplot(data)` or `sns.boxplot()`
violin/violin	Violin	`sns.violinplot()`
radar/radar	Radar	Custom with `ax = fig.add_subplot(111, polar=True)`
pie/pie	Pie	`ax.pie(sizes, labels=labels)`
histogram/histogram	Histogram	`ax.hist(data, bins=30)`
area/area	Stacked area	`ax.stackplot(x, y1, y2)`

§5 Mermaid Engine — Structured Diagrams

For flowcharts, sequence diagrams, class diagrams, state machines, Gantt charts.

Supported Diagram Types

Type	Keyword	Best for
Flowchart (vertical)	`flowchart TD`	Process flows, decision trees
Flowchart (horizontal)	`flowchart LR`	Pipelines, architectures
Sequence diagram	`sequenceDiagram`	API calls, message passing
Class diagram	`classDiagram`	OOP design, data models
State diagram	`stateDiagram-v2`	State machines, lifecycle
Gantt chart	`gantt`	Project timelines

Syntax Rules (critical for low-IQ models)

Node IDs: use simple letters — A, B, C (NOT Chinese, NOT spaces)
Labels: wrap in [] — A[Start Process]
Arrows: --> or -->|label|
NEVER use these characters inside labels: &, <, >
For decision nodes (diamond shape): use single braces — C{Is valid?}
Keep diagrams ≤15 nodes AND aesthetics not critical. For larger or visually polished diagrams → recommend NanoBanana (§6).

Rendering Protocol

Generate Mermaid code
Save to temp file: /tmp/rc_mermaid_{hash}.mmd
Render (try in order):
- mmdc -i /tmp/rc_mermaid_{hash}.mmd -o {output_path} -w 1920 -H 1080 --backgroundColor white
- npx --yes @mermaid-js/mermaid-cli -i /tmp/rc_mermaid_{hash}.mmd -o {output_path}
- Both fail → save .mmd file to workspace + tell user: "Mermaid rendering tool is not installed. The source file has been saved, please paste it into https://mermaid.live to view."
Check result: file exists + size > 1KB → SUCCESS

ReAct for Mermaid

If mmdc returns an error:

Parse the error message (usually "Parse error on line N")
Fix the syntax issue (often: special characters in labels, missing brackets)
Retry (max 3 attempts)

§6 AI Image Engine — NanoBanana (Complex Diagrams)

For complex academic diagrams that require visual polish: architecture diagrams, research methodology flows, concept maps, multi-layer system diagrams.

When to Use

Diagram has >15 nodes or complex spatial layout
User wants "beautiful/professional/publication-ready" quality
User explicitly requests AI-generated figure
Low-IQ model is active (AI Image quality is model-independent)

API Call Protocol

Step 0 — Confirm with user before calling the API (costs money):

"About to call NanoBanana (Gemini) to generate the image, expected to consume about $0.01 of API credit. Continue?" Wait for user confirmation. If user declines → fall back to §5 Mermaid.

Step 1 — Generate and execute a Python script via system.run:

import requests, base64, sys, os

API_KEY = os.environ.get('OPENROUTER_API_KEY', '')
if not API_KEY:
    print('ERROR: OPENROUTER_API_KEY not set', file=sys.stderr)
    sys.exit(1)

resp = requests.post(
    'https://openrouter.ai/api/v1/chat/completions',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'google/gemini-2.5-flash-preview-image-generation',
        'messages': [{
            'role': 'user',
            'content': 'Generate a professional academic diagram: {description}.\n\n'
                       'Style: clean, minimal, publication-ready, white background, '
                       'no watermark, clear English labels, professional color scheme '
                       '(blues, grays, muted tones), high resolution for academic paper.'
        }],
    },
    timeout=120,
)
resp.raise_for_status()
data = resp.json()

# Extract image from multimodal response
content = data['choices'][0]['message']['content']
b64_data = None
if isinstance(content, list):
    for part in content:
        if part.get('type') == 'image_url':
            url = part['image_url']['url']
            b64_data = url.split(',', 1)[1]
            break
        elif part.get('type') == 'image' and 'data' in part:
            b64_data = part['data']
            break
elif isinstance(content, str) and 'data:image' in content:
    b64_data = content.split(',', 1)[1]

if not b64_data:
    print('ERROR: No image found in API response', file=sys.stderr)
    sys.exit(1)

with open('{output_path}', 'wb') as f:
    f.write(base64.b64decode(b64_data))
print('OK')

Step 2 — Check: file exists + size > 1KB → SUCCESS.

If API call fails (timeout, auth error, quota exceeded):

Log the error
WARN user: "NanoBanana API call failed. Falling back to the Mermaid engine."
Fall back to §5 Mermaid Engine

§7 SVG Engine — Custom Vector Graphics

For geometric shapes, coordinate-annotated diagrams, simple custom illustrations.

Generation Method

Generate Python code using svgwrite:

import svgwrite

dwg = svgwrite.Drawing('{output_path}', size=('800px', '600px'))
dwg.add(dwg.rect(insert=(0, 0), size=('100%', '100%'), fill='white'))

# [YOUR SVG ELEMENTS HERE]

dwg.save()
print('OK')

If svgwrite is not available, generate raw SVG XML and save directly.

PNG conversion (optional):

Try: python3 -c "import cairosvg; cairosvg.svg2png(url='{svg_path}', write_to='{png_path}', dpi=300)"
If cairosvg unavailable: keep .svg file, inform user

§8 Quality Checklist (run after EVERY figure)

After generating a figure, MUST verify:

#	Check	How to verify	If FAIL
1	File exists	`ls -la {output_path}`	Re-run generation
2	File size > 1KB	Same command	File is corrupt → regenerate
3	Labels in English	Review generated code	Fix labels → re-run
4	DPI ≥ 300 (Python)	Check savefig params in code	Fix → re-run
5	No overlapping text	Visual inspection if possible	Add `tight_layout()` or adjust

If checks fail → fix and re-run (counts as one ReAct iteration).

§9 Academic Figure Standards

File Naming

Save all figures to: outputs/figures/{topic}-fig{N}.{ext}

Examples:

outputs/figures/transformer-fig1.png
outputs/figures/model-comparison-fig2.png
outputs/figures/methodology-flow-fig3.png

Caption Rule

Every figure MUST have an English caption. Present to user as:

Figure {N}. {Caption text describing what the figure shows.}

Citation Format

When embedding in text: "as shown in Figure {N}" or "see Figure {N}".

Style Rules

Font: sans-serif (Arial, Helvetica), ≥ 10pt for all text
DPI: 300 minimum (publication standard)
Background: white (no transparency)
Colors: colorblind-safe palettes (viridis, Set2, tab10, Paired)
Borders: thin axis lines (1-1.5pt), no box frames around plots
Grid: light gray (alpha 0.3), optional but recommended for data plots
Legend: positioned to avoid overlapping data; semi-transparent background

§10 Integration with Writing SOP

When called from writing-sop Phase 2 (first draft generation):

Writing-sop identifies a section needs a figure
It invokes this skill (plotting-sop) with the figure description
This skill generates the figure → workspace_save to outputs/figures/
Return to writing-sop with: figure path + caption
Writing-sop embeds the figure reference in the draft

Pattern for inline invocation:

[Writing-sop Phase 2, writing Methods section]
→ "This section needs a methodology flowchart"
→ [Load plotting-sop] → Engine selection → Generate → Save
→ [Return to writing-sop] → "See Figure 1" inserted in text

RC Local Tools Reference

Task	Tool	Example
Run Python plot	`system.run`	`python3 /tmp/rc_plot_abc.py`
Run Mermaid compile	`system.run`	`npx --yes @mermaid-js/mermaid-cli -i input.mmd -o output.png`
Call NanoBanana API	`system.run`	Python requests POST to OpenRouter endpoint
Save figure	`workspace_save`	`outputs/figures/{name}.png`
Check file	`system.run`	`ls -la outputs/figures/{name}.png`
Install deps (if needed)	`system.run`	`pip install matplotlib seaborn`