plotting-sop

name	Plotting SOP
description	Standard operating procedure for academic figure generation. Four rendering engines: Python (data viz), Mermaid (flowcharts), AI Image via NanoBanana/OpenRouter (complex diagrams), SVG (vector). Includes engine selection decision tree, ReAct self-correction, NanoBanana configuration, environment detection, and academic style rules.

Plotting SOP — 科研作图标准操作规程

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

1. Tell user: "Python 科学绘图库未安装。是否允许我运行安装脚本？(约 30 秒)"
2. If user agrees: bash scripts/setup-plotting-env.sh
3. If setup script not found: pip install --user matplotlib seaborn numpy pandas
4. 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:

"这类复杂的学术图表，推荐使用 NanoBanana（基于 Gemini 图片生成）来获得最佳效果。 您只需提供一个 OpenRouter API Key（https://openrouter.ai/settings/keys）。 如果您不想配置，我也可以使用本地工具（Mermaid/Python）尝试生成，但质量可能有限。"

---

§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

1. Generate code following the template above
2. Save code to temp file: system.run with inline Python or write to /tmp/rc_plot_{hash}.py
3. Execute: python3 /tmp/rc_plot_{hash}.py
4. 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 作图失败。请检查数据格式或简化图表要求。"

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	Grouped bar	ax.bar(x, y)
折线图/line chart	Line plot	ax.plot(x, y)
散点图/scatter	Scatter	ax.scatter(x, y)
热力图/heatmap	Heatmap	import seaborn as sns; sns.heatmap(data)
箱线图/box plot	Box	ax.boxplot(data) or sns.boxplot()
小提琴图/violin	Violin	sns.violinplot()
雷达图/radar	Radar	Custom with ax = fig.add_subplot(111, polar=True)
饼图/pie	Pie	ax.pie(sizes, labels=labels)
直方图/histogram	Histogram	ax.hist(data, bins=30)
面积图/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)

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

Rendering Protocol

1. Generate Mermaid code
2. Save to temp file: /tmp/rc_mermaid_{hash}.mmd
3. 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 渲染工具未安装。已保存源文件，请粘贴到 https://mermaid.live 查看。"
4. 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 "美观/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):

"即将调用 NanoBanana (Gemini) 生成图片，预计消耗约 $0.01 API 额度。是否继续？" 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 调用失败。降级到 Mermaid 引擎。"
• 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):

1. Writing-sop identifies a section needs a figure
2. It invokes this skill (plotting-sop) with the figure description
3. This skill generates the figure → workspace_save to outputs/figures/
4. Return to writing-sop with: figure path + caption
5. 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