/figure

name: 科研可视化工具
description: >-
  从数据剖析到出版级成图的完整可视化工具。先做数据剖析（列类型/样本量/分布/异常值/分组结构/相关性），
  再结合论证目标推荐图型，主动拦截科研画图经典错误，产出 Nature / Science / IEEE / Elsevier / PNAS /
  中文核心期刊级别的成图。覆盖数据 EDA、图表契约、选图决策、出版级绘制、程序自检 + AI 读图闭环、多格式
  导出和文件审计。数学建模场景额外支持三类图体系（原始数据/过程/结果）、子问题覆盖检查和建模流程图规范。
  当用户涉及论文配图、科研画图、数据可视化、选图、期刊投稿图、figure、出版级图表、matplotlib、seaborn、
  plotly、误差棒、显著性标注、色盲安全配色、矢量图导出、中文论文图表、多面板时使用。

科研可视化工具

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

路径

• `SKILL_ROOT`：math-modeling-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 曲面、多面板组合。**不做**示意图、架构图。

**额外覆盖建模流程图**：数学建模场景的总体/子问题方法流程图走 `references/chart-types/flowchart.md`。 流程图属于方法与结构示意，**不占用三类候选图配额**，也不替代结果图。

工作流

第 1 步：数据剖析

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**：

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**：

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'],
    size_inches=(3.5, 2.625),
    dpi=300,
    grayscale_preview=True,
)

**MATLAB**：使用 `export_publication_figure(fig, 'figs/fig1', 'png', 300)` 或 `export_publication_figure(fig, 'figs/fig1', 'svg')`。

数学建模场景（两种语言均适用）：同时输出 SVG 与至少 300 DPI PNG。

第 9 步：文件审计

两个脚本职责不同，按顺序执行：

# 1. 编程手自检：文件格式/DPI/字体合规（每张图都过）
python "<SKILL_ROOT>/tools/figure/scripts/check_figure.py" "<PROJECT_ROOT>/figures" --strict

# 2. 数学建模 P2 门禁：三类图数量 + 子问题覆盖（终检时由质检 Subagent 执行）
python "<SKILL_ROOT>/references/roles/编程手/scripts/figure_audit.py" "<PROJECT_ROOT>/figures" --questions q1 q2 ... qN --strict

• `check_figure.py`：检查单张图的格式合规性（DPI、字体、尺寸、矢量格式），编程手每次导出后自检用。
• `figure_audit.py`：检查三类图数量是否达标、子问题是否全覆盖，P2 编程终检时由独立质检 Subagent 执行。

主动拦截（顾问职责）

发现用户需求触发以下错误时，**先说明再给替代方案，不要默默照做**。完整清单见 `tools/figure/references/design/viz_pitfalls.md`。

| 错误 | 后果 | 替代方案 | |---|---|---| | n<10/组 还想画均值柱 | 掩盖分布、掩盖 n | 箱线 + stripplot | | 双 Y 轴显示无关变量 | 视觉假相关 | 拆成上下子图共享 x | | 用饼图展示占比 | 人眼判角度差长度 3 倍 | 横向柱状（按值排序） | | 3D 柱 / 3D 饼 | 视角扭曲数值 | 2D 柱、热力图 | | 比例图 Y 轴不从 0 起 | 误导小差异 | 从 0 起或用 log | | x 是分类却用折线连均值 | 暗示假连续 | 散点/点图/柱状 | | rainbow / jet 色图 | 感知不均匀 | viridis / magma / RdBu_r |

尊重用户最终决定，但**留下明确的劝阻记录**。

参考文档

`tools/figure/references/` 下文档——**按需读，不要一次全读**：

选图与决策

| 文档 | 何时读 | |---|---| | `chart-types/chart_selection.md` | **每次选图必读**——决策框架、不同论点→不同图 | | `chart-types/flowchart.md` | 需要画总体/子问题建模流程图时读——样式、生成路线、导出与自检 | | `guides/figure_contract.md` | 多面板图的契约工作流——核心结论→证据链→面板映射→审稿人风险 |

配方与模板

| 文档 | 何时读 | |---|---| | `api-templates/plot_recipes.md` | 各类图完整配方（含数学建模专用模式） | | `guides/tutorials.md` | 端到端可运行教程——分组柱状/收敛曲线/热力图/森林图 | | `api-templates/api.md` | 可复用辅助函数（make_grouped_bar/make_trend/make_heatmap 等） | | `api-templates/template_catalog.md` | CSV 驱动模板—