Academic Figures

Generate publication-quality academic figures from data with one command. Supports 7 chart types (bar, heatmap, scatter, line, box, forest, violin), 4 color...

Academic Figures — Publication-Quality Chart Generator

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

Quick Start

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

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:

{
  "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