Academic Figures

SKILL.md

---
name: academic-figures
description: >
  Generate publication-quality academic figures from data with one command.
  Supports 7 chart types (bar, heatmap, scatter, line, box, forest, violin),
  4 color themes (Nature, Lancet, conservative, default), CJK/Chinese auto-detection
  with zero garbled text, bilingual labels, statistical annotations (error bars,
  significance markers, trend lines, CI bands), and dual output (PNG 300dpi + SVG).
  Use when creating charts, plots, or figures for papers, presentations, or reports.
  Triggers on: "make a figure", "generate chart", "plot data", "create bar chart",
  "heatmap", "scatter plot", "forest plot", "box plot", "line chart", "violin plot", "论文配图",
  "画图", "柱状图", "热力图", "散点图", "森林图", "箱线图", "折线图".
---

# Academic Figures — Publication-Quality Chart Generator

Generate figures from JSON/CSV data. Local execution, no data leaves the machine.

## Quick Start

```bash
# Bar chart with CJK support
python3 scripts/gen_figure.py -t bar -d data.json -o figure.png --cjk \
  --title "图2 主标题 / Subtitle" --ylabel "准确率 Accuracy (%)"

# Heatmap
python3 scripts/gen_figure.py -t heatmap -d data.json -o heatmap.png --cjk \
  --cmap RdBu_r --vmin -20 --vmax 45

# Scatter with trend line
python3 scripts/gen_figure.py -t scatter -d data.csv -o scatter.png \
  --xlabel "Baseline (%)" --ylabel "Gain (%)" --theme nature
```

## Chart Types

| Type | Command | Key Features |
|------|---------|-------------|
| Bar | `-t bar` | Grouped bars, error bars, significance brackets |
| Heatmap | `-t heatmap` | Cell annotations, custom colormap, colorbar |
| Scatter | `-t scatter` | Trend line, r value, color grouping, mean points |
| Line | `-t line` | Multiple series, error bands, markers |
| Box | `-t box` | Box-and-whisker, jitter points |
| Forest | `-t forest` | CI whiskers, overall diamond, ref line |
| Violin | `-t violin` | Density estimation, inner mean/median |

## Color Themes

- `--theme nature` — Nature journal palette (vibrant, distinct)
- `--theme lancet` — Lancet medical palette (bold, high-contrast)
- `--theme conservative` — Professional muted (safe for any field)
- `--theme default` — Balanced, versatile

## CJK / Chinese Support

Pass `--cjk` to auto-detect and load system CJK fonts. Zero manual configuration needed.

```bash
python3 scripts/gen_figure.py -t bar -d data.json -o fig.png --cjk
```

Font detection priority: Noto Sans CJK → PingFang → Microsoft YaHei → WQY → AR PL → Droid.

For custom font: `--cjk-font /path/to/font.ttf`

## Data Input

JSON (full features) or CSV (basic). See `references/data-formats.md` for complete schema per chart type.

**JSON bar chart example:**
```json
{
  "labels": ["Group A", "Group B"],
  "series": {"Treatment": [75, 82], "Control": [68, 70]},
  "errors": {"Treatment": [3, 2], "Control": [2, 1]},
  "significance": {"Treatment:0": "***", "Control:1": "NS"}
}
```

## Key Flags

| Flag | Description |
|------|-------------|
| `--title "text"` | Figure title. Supports `\n` for newline (works in shell with `$'line1\nline2'` or when called from Python) |
| `--xlabel`, `--ylabel` | Axis labels |
| `--width N`, `--height N` | Figure size in inches |
| `--show-values` | Show numeric labels on bars |
| `--no-trend` | Hide trend line (scatter) |
| `--no-legend` | Hide legend |
| `--cmap NAME` | Colormap (heatmap) |
| `--vmin`, `--vmax` | Value range (heatmap) |

## Output

- `.png` — 300 DPI raster (default)
- `.svg` — Vector (pass `.svg` extension to `--out`)

## When Agent Generates Figures (Not CLI)

If creating a figure via Python script rather than CLI:

1. Always call `detect_cjk_font()` first if any label may contain CJK
2. Use `fontproperties=font_prop` on all text-setting calls with CJK content
3. Set `plt.rcParams['axes.unicode_minus'] = False` (prevents minus sign boxes)
4. Verify output: file size > 20KB for multi-label charts indicates font loaded
5. Preferred output: PNG at 300 DPI, `bbox_inches='tight'`, white background