scipilot-figure-skill

scipilot-figure-skill — 科研数据可视化顾问

SciPilot Skills 家族成员 | 从数据剖析到出版级成图

概述

科研工作者最大的画图痛点往往不是"不会用 matplotlib"，而是"手上一堆数据，不知道该用什么图把结论讲清楚"。本技能的首要能力是【思考与判断】，其次才是【绘制】。

具体地——永远先思考再画：

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

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

何时使用

• 用户给了一个 CSV / Excel / DataFrame 说"帮我画一下"或"用什么图好"
• 用户在写论文要插数据图
• 用户已有草图但说"达不到投稿要求"
• 用户提到 Nature / Science / IEEE 等具体期刊
• 用户问"中文论文 matplotlib 出方框怎么办"
• 用户提到误差棒、显著性、色盲、矢量导出、多面板

核心工作流（8 步）

这是本技能与普通画图工具的根本区别——不能上来就画。每一步缺位前一步的成果都不该执行。

第 0 步：理解任务

开画前先搞清楚两件事：

1. 这张图要论证什么观点 / 回答什么问题？ 同样数据，论点不同图就不同（详见 references/chart_selection.md 的"同一批数据、不同论点 → 不同图"小节）
2. 数据在哪里？长什么样？ 文件路径 / 字段含义 / 多少行 / 是否已经清洗

如果用户没说清论证目标，主动问一句："你这张图主要想说服读者相信什么？" 或从论文上下文推断并明确告诉用户你的假设。不要默认"用户知道自己要什么"。

第 1 步：剖析数据

调用 scripts/profile_data.py：

python scripts/profile_data.py data.csv --group group --group condition

输出包含：每列类型、样本量、缺失率、连续列的描述统计 + 偏度 + 异常值、分组样本量分布、相关性矩阵、初步图型建议。

不会读这份报告？查 references/data_profiling.md。

重点核对：

• 列类型识别对不对？（数字 ID 被认成 ordinal 是常见误判）
• 每组 n 是多少？小样本警告？
• 是否高度偏态？是否需要对数轴？

第 2 步：选图

这是顾问职责的核心。基于第 0、1 步的事实，查 references/chart_selection.md 的决策框架决定图型。要点：

• 给出推荐 + 简短理由 + 1-2 个备选（不要只丢一个选择给用户）
• 如果数据维度过多（如分组组合 > 12）→ 明确建议拆图，而不是硬塞
• 如果用户指定的图型不适合数据（如 n=5 要画均值柱）→ 善意指出问题并说明更好的选择，让用户决定。详见下方"主动拦截"小节
• 如果数据特征意味着特殊处理（双峰分布、严重异常值、跨量级）→ 在选图建议里明确提及

第 3 步：查期刊规范

确定目标期刊后查 references/journal_specs.md 拿到：单/双栏宽（mm 与 inch）、字号、推荐字体、DPI、矢量格式偏好。

不知道目标期刊就问一句。"毕业论文 / 中文核心 / 英文 SCI / NeurIPS" 都对应不同规范。

第 4 步：配环境

from setup_style import setup_style
setup_style(journal='nature', lang='en')             # 英文 Nature
setup_style(journal='general', lang='zh', serif_for_zh=True)   # 中文宋体混排

SciencePlots 装了自动用，没装回退到内置预设——不会因为缺它崩溃。

第 5 步：绘制

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

画图时强制做到：

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

第 6 步：自检闭环（机器 + AI 读图）

三层都要过，缺一层都可能带病投稿：

1. 语义层：references/viz_pitfalls.md 18 条科研画图禁忌——图型/配色/误差是否踩坑
2. 形式层：references/publication_checklist.md 形式合规（尺寸、DPI、字号、误差交代）
3. 视觉层（v2.1 新增）：出图后渲染 PNG → 程序自检 → AI 读图复核 → 回改的闭环：
   • visual_qa.render_preview(fig, 'figs/_preview.png') 渲一张预览
   • visual_qa.audit_layout(fig) 程序抓缺字乱码 / 文字裁切 / 刻度重叠（确定性问题）
   • 用 Read 工具读这张 PNG，对照 references/visual_review.md 的 8 项清单核对 图例压数据 / 子图标签对齐 / 配色灰度可分（程序难判的感知问题）
   • 发现问题 → 按 visual_review.md 回改表改 → 重渲 → 再读，直到通过

任何一层不通过就回去改图。矢量图的导出放在闭环通过之后，把问题挡在投稿之前。

第 7 步：导出

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,    # 自动出灰度版供色盲检查
)

最后跑一遍 scripts/check_figure.py --strict 机器审计。

选图速查（详细决策在 chart_selection.md）

数据形态	推荐首选	不该用
1 个连续 看分布	直方图 + KDE / 箱线	饼图
1 个分类 看占比	横向柱状（按值排序）	饼图、3D 饼
1 分类 + 1 连续，n<10/组	stripplot / dot plot（直接列点）	均值柱（严禁）
1 分类 + 1 连续，n≥10/组	箱线/小提琴 + stripplot 叠加	仅均值柱
2 连续 看关系	散点 + 回归 + r 值	折线（除非 x 有序连续）
时间 / 剂量 vs 连续	折线 + 误差带	柱状
多变量相关（>3 列）	相关性热力图 / pairplot	平行坐标
矩阵数据	热力图（viridis/RdBu_r）	3D 表面、rainbow 色图
构成占比	堆叠柱 / treemap	饼图

完整决策树和"同一数据不同论点 → 不同图"对照表见 chart_selection.md。

五条硬性原则

原则 1：按最终尺寸出图，不二次缩放

figsize 直接设论文里实际尺寸（Nature 单栏 3.5 in、双栏 7.2 in；IEEE 单栏 3.5 in、双栏 7.16 in）。导出后绝不在 Word / LaTeX 里再缩放。

为什么：matplotlib 字号是绝对单位（pt），Word 里缩 50% 9pt 就变 4.5pt——投稿前自检直接打回。

原则 2：矢量优先

折线 / 柱状 / 散点 / 热力（数据网格除外）/ 误差棒 → PDF / SVG / EPS。显微图、照片才用 TIFF / PNG（300-600 DPI）。绝对不用 JPEG。

为什么：矢量任意缩放不糊，文字仍可选；JPEG 数据图边缘有压缩 artifact，期刊 PDF 检查器直接打回。

原则 3：配色对色盲友好

默认 seaborn.color_palette('colorblind') 或 Okabe-Ito。同一张图不同类别加冗余编码（线型 / marker）。出图前 export_figure(..., grayscale_preview=True) 看灰度版能否区分。

为什么：约 8% 男性、0.5% 女性色觉异常。审稿人里有这群人，全靠红绿区分的图对他们传达力归零。

原则 4：字号在最终尺寸下可读

正文标签和刻度数字 7-9 pt，最小字 ≥ 6 pt。

为什么：审稿编辑会按 mm 打印查字号；<6 pt 不可读直接退回。

原则 5：误差必有交代

只要有误差棒 / 阴影区间 / 箱线——图注必须写清：

• 误差类型（SD / SEM / 95% CI / IQR）
• 样本量 n
• 显著性检验方法 + 校正（如 Bonferroni）
• 显著性符号定义（* p<0.05 等）

为什么：SD 和 SEM 差一个 √n。混淆 = 结论反转 = 退稿。

積極的な介入（アドバイザーの役割）

ユーザーの要望が以下の誤りにつながる場合は、まず説明してから代替案を提示し、黙ってそのまま実行しないでください。全15項目については references/viz_pitfalls.md を参照してください。

誤り	結果	代替案
1グループあたり n<10 なのに平均値の棒グラフを描く	分布や n が隠れ、査読者に疑念を持たれる	箱ひげ図 + stripplot、または stripplot のみ
無関係な変数を二重 Y 軸で表示する	見た目上の相関や乖離が、作図者によって捏造される	x 軸を共有する上下のサブプロットに分ける、または標準化して共通軸にする
割合の表示に円グラフを使う	人間の目は角度の差を長さの差の3倍正確に判別する	横棒グラフ（値順に並べる）
3D の棒グラフ / 円グラフ	視点によってすべての数値が歪む	2D の棒グラフ、ヒートマップ
比率グラフで Y 軸を 0 から始めない	小さな差が大きく見え、誤解を招く	0 から始めるか log を使う、または明確な軸の切断マークを付ける
連続値を colorbar なしで色に割り当てる	読者が色の濃淡と数値の対応を把握できない	colorbar を必ず付け、ラベル / 単位を明記する
x 軸がカテゴリなのに、平均値を折れ線でつなぐ	存在しない連続的な関係を示唆する	散布図 / ドットプロット / 棒グラフ
1つの図に5つの論点を詰め込む	論点がなくなる	図を分け、1枚につき中心となる結論を1つにする
rainbow / jet のカラーマップ	知覚的に不均一で、偽のピークを生み出す	viridis / magma / RdBu_r

介入時の文例：

ご希望の「各5サンプル、3グループの平均値棒グラフ」は、P1（平均値棒グラフが分布を隠す）に該当します。n=5 は小さすぎるため、棒グラフでは査読者に何かを隠しているのではと疑われる可能性があります。箱ひげ図 + stripplot を重ねて各点を表示する形をおすすめします。5点すべてが見えて、分布の形もひと目で分かります。元の案のまま作図しますか？

ユーザーの最終決定は尊重しますが、明確な注意喚起の記録を残してください。

中国語のサポート

中国語の文字が matplotlib で豆腐（文字化けした四角形）になる根本的な原因は、デフォルトのフォント（DejaVu Sans など）に CJK の文字セットが含まれていないことです。setup_style(lang='zh') は次の2つを自動で行います。

1. 優先順位に従って中国語フォントを検索します：Noto Sans CJK SC > Source Han Sans SC > SimHei > Microsoft YaHei
2. マイナス記号が豆腐になる問題を修正します：plt.rcParams['axes.unicode_minus'] = False

CJK フォントが1つも見つからない場合は、明確なインストール案内を表示します（作図後に文字が豆腐になっていると判明する事態を防ぎます）。

中国語の学術誌で使われる「宋体 + 数字は Times New Roman」の混植：serif_for_zh=True を渡すと、Noto Serif CJK / Source Han Serif / SimSun を優先して選択します。

詳しくは references/journal_specs.md 末尾のフォントのインストールに関する節を参照してください。

スクリプトの説明

スクリプト	役割	主なエントリーポイント
profile_data.py	EDA：列の型 / サンプル数 / 分布 / 外れ値 / 相関 / 初期の図の種類の提案	profile_data(source, group_cols)
setup_style.py	学術誌のプリセット + CJK フォント設定 + SciencePlots のラッパー	setup_style(journal, lang, use_sciplots, serif_for_zh)
export_figure.py	複数形式 + 最終サイズに合わせた出力 + グレースケールのプレビュー	export_figure(fig, basename, formats, dpi, size_inches, grayscale_preview)
check_figure.py	ファイルの適合性の自動チェック（形式 / DPI / フォントの埋め込み）	check_figure(path, min_dpi, target_inches)
layout_tools.py	サブプロットラベルの配置調整 + constrained/tight によるレイアウトのフォールバック	add_panel_labels(fig, style) / finalize_figure(fig)
visual_qa.py	PNG プレビューのレンダリング + プログラムによる自動チェック（文字の欠落 / 切り抜き / 目盛りの重なり）	render_preview(fig, out) / audit_layout(fig)

参考ドキュメント

references/ には7つのドキュメントがあります。必要に応じて参照し、一度にすべて読まないでください。

ドキュメント	参照するタイミング
chart_selection.md	図を選ぶたびに必読——意思決定のフレームワーク、論点ごとに適した図
data_profiling.md	profile_data.py の出力が理解できないとき
viz_pitfalls.md	自動チェック前に必読——18項目の落とし穴リスト（P16-18 のレイアウト / レンダリングの落とし穴を含む）
journal_specs.md	対象の学術誌のカラム幅 / フォントサイズ / DPI / フォントが不明なとき
plot_recipes.md	9種類の図それぞれの完全なレシピ + 適用場面
publication_checklist.md	投稿前の最終的な形式適合チェックリスト
visual_review.md	作図後の目視チェック——AI による図の読み取り8項目チェックリスト + 修正サイクルのプロトコル

各ドキュメントの冒頭に目次があります。まず目次で該当箇所を探し、その節を参照してください。

よくあるタスクの例

タスク A：ユーザーが CSV だけを渡して「これを論文用の図にして」と依頼する

検討から作図までのワークフロー例：

1. ステップ 0：ユーザーに「このデータで、読者に何を納得してほしいですか？」と尋ねます。グループ間の差でしょうか、時間的な傾向でしょうか、変数間の関係でしょうか。
2. ステップ 1：python scripts/profile_data.py data.csv を実行し、データ分析レポートを取得します。
3. ステップ 2：レポートの「列の型 + サンプル数 + グループ構造」を読み、ユーザーの論証目標と照らし合わせて chart_selection.md の意思決定フレームワークを参照します。おすすめの図とその理由、代替案を1～2案、積極的に提示してください。
4. ユーザーの確認を得てから、ステップ 3～7 に進みます：学術誌の規定の確認、環境の設定、作図、自動チェック、出力。

どのステップも省略しないでください。

タスク B：ユーザーが「各5サンプル、3グループの平均値を棒グラフで表示したい」と言う

積極的な介入の例：

你要的"三组各 5 个样本均值柱状图"会触发科研画图的经典 P1 错误
（参见 viz_pitfalls.md）——n=5 太小，柱状图的高度 + 一根误差棒无法
告诉读者数据真实分布。审稿人看到很可能要求"show individual data points"。

我建议改成 **箱线图 + stripplot 叠加每个点**：5 个点直接可见，
不掩盖任何信息，反而更可信。代码也只多一行。

要按原方案画，还是改成箱线+stripplot？

ユーザーが棒グラフにこだわる場合は、そのとおりに作図します。ただし、少なくとも stripplot を重ねて各点を表示してください。

タスク C：複数パネルの組み合わせ図

ユーザー：「Figure 1 を作ってください。4つの panel があり、それぞれ PCA、loss 曲線、混同行列、生存曲線を表示します。」

手順：

1. 対象の学術誌を確認します（図全体を 7.2 in にするか 7.16 in にするか、Nature の a/b/c と IEEE の (a)(b)(c) のどちらを使うかを決めます）。
2. 各 panel を個別に作図し、フォントサイズ、配色、座標軸のスケールを統一します（同じ変数は4つの panel すべてで同じ色にします）。
3. plt.subplots(2, 2, figsize=(7.2, 5.4)) で組み合わせます（setup_style では constrained_layout がデフォルトで有効になっています）。
4. layout_tools.finalize_figure(fig) でレイアウトを整え、add_panel_labels(fig, style='nature') で a/b/c/d を付けます。figure 座標に基づいて横方向・縦方向に自動で位置をそろえるため、位置がずれやすい ax.text の手動配置は避けてください（viz_pitfalls P18 を参照。IEEE では style='ieee' を使い、(a)(b)(c) の形式にします）。
5. 目視チェックのサイクル：render_preview で PNG をレンダリング → audit_layout でプログラムによる自動チェック → Read で図を読み取り、サブプロットの位置合わせ / 重なりを確認 → 修正 → 問題がなければ出力し、グレースケールを確認します。

詳しいレシピは plot_recipes.md の第9節を参照してください。

タスク D：有意差の注記付き統計図

ユーザー：「3グループのデータを、箱ひげ図と有意差の注記付きで表示したい。」

手順：

1. profile で n を確認します（n<10 の場合は stripplot を重ねる必要があります）。
2. 統計検定を実行します（ユーザーは使用した検定方法と、多重比較補正の有無を必ず伝えてください）。
3. 箱ひげ図 + stripplot を作成します。
4. matplotlib.lines.Line2D または statannotations を使って、グループ間に有意差を示すブリッジを描きます。
5. 図注には必ず、誤差の種類 / n / 検定方法 / 補正 / 記号の意味を記載します。

レシピは plot_recipes.md の第4節を参照してください。

依存関係

matplotlib>=3.7
seaborn>=0.13
plotly>=5.18
pandas>=2.0
numpy>=1.24
scipy>=1.10            # profile_data 的偏度计算用到
Pillow>=10.0           # check_figure / grayscale preview
SciencePlots>=2.1      # 可选；装了样式更接近期刊
pypdf>=4.0             # 可选；check_figure 字体嵌入检查
kaleido>=0.2.1         # 可选；plotly 导出 PDF/PNG

オプションの依存関係が不足していても、このスキルは引き続き実行できます。適切に機能を縮退させ、その旨を通知します。