科研可视化工具

Files (30)

• SKILL.md
• 可视化面板模板.html · assets/
• api.md · references/api-templates/
• plot_recipes.md · references/api-templates/
• template_catalog.md · references/api-templates/
• chart_selection.md · references/chart-types/
• chart_types.md · references/chart-types/
• common_patterns.md · references/design/
• design_theory.md · references/design/
• viz_pitfalls.md · references/design/
• asset_adaptation.md · references/guides/
• data_profiling.md · references/guides/
• figure_contract.md · references/guides/
• figure_legend_conventions.md · references/guides/
• nature_2026_observations.md · references/guides/
• tutorials.md · references/guides/
• journal_specs.md · references/quality/
• publication_checklist.md · references/quality/
• qa_contract.md · references/quality/
• visual_review.md · references/quality/
• check_figure.py · scripts/
• export_figure.py · scripts/
• layout_tools.py · scripts/
• profile_data.py · scripts/
• setup_style.py · scripts/
• style_constants.py · scripts/
• validate_figure.py · scripts/
• visual_qa.py · scripts/
• contract.md · static/core/
• stance.md · static/core/

SKILL.md (first lines)

# 科研可视化工具

> 从数据剖析到出版级成图 | Python + MATLAB | 自检 + AI 读图闭环

## 路径

- `SKILL_ROOT`：mathmodel-skill 仓库根目录（只读）。
- 本文件中所有 `tools/figure/...` 路径均相对于 `SKILL_ROOT`。
- CLI 命令使用 `"<SKILL_ROOT>/tools/figure/scripts/..."` 格式，确保从任何工作目录均可执行。
- Python import 使用 `sys.path.insert(0, os.path.join(SKILL_ROOT, 'tools', 'figure', 'scripts'))` 后导入。

## 概述

本工具融合 nature-figure 的图表契约/后端路由架构与 scipilot-figure-skill 的数据剖析/选图决策/自检闭环，
并扩展数学建模特有的三类图体系和子问题覆盖检查。**永远先思考再画**：

1. 先理解数据再选图——拿到数据先做 EDA，用事实驱动图型选择
2. 先想清楚"这张图要论证什么"——同样数据，不同论点 = 不同图
3. 主动拦截科研画图的经典错误，而不是顺从
4. 维度太多就建议拆图，不硬塞

**只覆盖纯数据图**：折线、柱状、散点、箱线/小提琴、热力图、误差棒、分布图、相关性矩阵、雷达图、
3D 曲面、多面板组合。**不做**示意图、流程图、架构图。

## 工作流

### 第 1 步：数据剖析

```bash
python "<SKILL_ROOT>/tools/figure/scripts/profile_data.py" data.csv --group group --group condition
```

输出：每列类型、样本量、缺失率、连续列描述统计 + 偏度 + 异常值、分组样本量分布、相关性矩阵、初步图型建议。
不会读报告？查 `tools/figure/references/guides/data_profiling.md`。

**重点核对**：列类型识别对不对？每组 n 是多少？是否高度偏态？是否需要对数轴？

**数学建模场景**：从题目分析报告提取全部子问题并规范为 `q1…qN`，按子问题核对行列、类型、缺失、
分组样本量、分布、异常值和单位。

### 第 2 步：图表契约

在选图之前，先填写五点契约（详见 `tools/figure/static/core/contract.md`）：

1. **核心结论**：一句话写出这张图必须捍卫的论点
2. **证据链**：每个面板对应论点的哪个证据环节
3. **版型**：quantitative grid / schematic-led composite / image plate + quant / asymmetric mixed-modality
4. **后端**：Python 或 MATLAB
5. **期刊/导出规范**：最终尺寸、可编辑文字、源数据、统计口径、导出格式

### 第 3 步：选图决策

**永远先选图型，再画图。** 图型选错，画得再好看也没用。

基于第 1、2 步的事实，查 `tools/figure/references/chart-types/chart_selection.md` 的决策框架：

- **按数据形态选图**：连续变量看分布→直方图/KDE/箱线，分类+连续看比较→箱线/柱状，两连续看关系→散点+回归，时间趋势→折线，多变量相关→热力图/pairplot
- **按论证意图选图**：同一批数据，不同论点→不同图（"整体差异"用箱线，"动态变化"用折线，"个体差异"用散点）
- **给出推荐 + 简短理由 + 1-2 个备选**
- 数据维度过多（分组组合 > 12）→ **明确建议拆图**
- 用户指定图型不适合数据 → **善意指出问题并说明更好的选择**（如 n<10 要画均值柱→建议箱线/stripplot）
- 数学建模场景：查 `chart_selection.md` 末尾的"数学建模场景速查"表
- **图型多样**：全文图型种类 ≥ 3 种，避免全部柱状或全部折线；每个面板回答唯一问题，不重复展示相同数据（详见 `design_theory.md` §11 反冗余清单）

### 第 4 步：查期刊规范

确定目标期刊后查 `tools/figure/references/quality/journal_specs.md` 拿到：单/双栏宽（mm 与 inch）、字号、
推荐字体、DPI、矢量格式偏好。不知道目标期刊就问一句。

### 第 5 步：配环境

**Python**：

```python
import sys, os
sys.path.insert(0, os.path.join(SKILL_ROOT, 'tools', 'figure', 'scripts'))
from setup_style import setup_style
setup_style(journal='nature', lang='en')             # 英文 Nature
setup_style(journal='general', lang='zh', serif_for_zh=True)   # 中文宋体混排
```

`SciencePlots` 装了自动用，没装回退到内置预设。

**MATLAB**：将 `references/roles/编程手/scripts/apply_publication_style.m` 复制到 `PROJECT_ROOT/utils/` 后调用。

### 第 6 步：绘制

按 `tools/figure/references/api-templates/plot_recipes.md` 对应章节的配方画。每节都有可直接复制的代码 + 常见坑。

**Python** 画图时强制做到：
- `figsize=(目标宽, 目标高)` 单位英寸——直接定最终尺寸
- 用 `seaborn.color_palette('colorblind')` 或 Okabe-Ito + 冗余编码（不同线型/marker）
- 误差棒/阴影要在图注交代是 SD / SEM / 95% CI + n

**MATLAB**：按 `references/roles/编程手/scripts/apply_publication_style.m` 的出版规范绘制，用 `export_publication_figure()` 导出。

数学建模场景（两种语言均适用）：按三类图体系生成（原始数据图 / 过程图 / 结果图），每类至少 3 张、合计至少 9 张，且每个子问题在三类中各至少 1 张。**每类内部图型要有变化**（如原始数据类至少含 1 张分布图 + 1 张关系图），全文图型种类 ≥ 3 种。

### 第 7 步：自检闭环（三层全过）

1. **语义层**：`tools/figure/references/design/viz_pitfalls.md` 18+ 条避坑清单——图型/配色/误差是否踩坑
2. **形式层**：`tools/figure/references/quality/publication_checklist.md` 形式合规（尺寸、DPI、字号、误差交代）
3. **视觉层**：
   - **Python**：`tools/figure/scripts/visual_qa.render_preview(fig, 'figs/_preview.png')` 渲预览，`tools/figure/scripts/visual_qa.audit_layout(fig)` 程序抓缺字/裁切/重叠
   - **MATLAB**：用 `export_publication_figure()` 导出 PNG 后人工检查
   - 用 Read 工具读 PNG，对照 `tools/figure/references/quality/visual_review.md` 的 8 项清单核对
   - 发现问题 → 回改 → 重渲 → 再读，最多 3 轮

### 第 8 步：导出

**Python**：

```python
import sys, os
sys.path.insert(0, os.path.join(SKILL_ROOT, 'tools', 'figure', 'scripts'))
from export_figure import export_figure
export_figure(
    fig, basename='figs/fig1',
    formats=['pdf', 'svg', 'png'],

From rootkiller6788/mathmodel-skill, MIT.

More from rootkiller6788/mathmodel-skill