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.svgextension to--out)
When Agent Generates Figures (Not CLI)
If creating a figure via Python script rather than CLI:
- Always call
detect_cjk_font()first if any label may contain CJK - Use
fontproperties=font_propon all text-setting calls with CJK content - Set
plt.rcParams['axes.unicode_minus'] = False(prevents minus sign boxes) - Verify output: file size > 20KB for multi-label charts indicates font loaded
- Preferred output: PNG at 300 DPI,
bbox_inches='tight', white background