scientific-figure

科学論文用図

ジャーナルが受け入れるサイズに変更せずに済むよう、ジャーナルが受け入れる PDF／PNG を出力し、正確なジャーナル寸法（mm／pt）で投稿品質のマルチパネル図を作成します。書き出し前に、フォントサイズがジャーナルの最小要件を満たしているか検証します。

このスキルが必要な理由

以前の react-pdf ワークフローには、構造上の問題が2つありました。

1. 構成が物理サイズに準拠していませんでした。 レンダリング中に、Flexbox レイアウトが寸法を微妙にずらしていました。
2. フォントが読みやすさの基準を下回るまで縮小されていました。 コンテンツがはみ出すと、react-pdf が図全体を一律に拡大縮小し、軸ラベルが4 pt未満になることがありました。

このスキルは、そのワークフローに代わるものです。パネルは正確な mm 座標に配置され、テキストは SVG の <text> 要素として保持されるため、書き出し前にフォントサイズを確認できます。また、フォントの最小値に違反した場合、バリデーターは図全体ではなく個々のパネルを拡大縮小します。

パイプライン

1. Plan        2. Build elements        3. Compose          4. Validate fonts     5. Export
   (journal      (matplotlib/seaborn      (svgutils, at        (per-element pt vs    (Inkscape if
    size, panel   per panel; SVG out;     exact mm/pt;         journal minimum;      present;
    grid)         optional icons)         text preserved)      rescale panel if      cairosvg
                                                               below minimum)        otherwise)

各ステップでは uv run --with によるオンザフライ実行を使用するため、このスキル自体を恒久的にインストールする必要はありません。

ステップ1：図を計画する

何かを生成する前に、次の項目を決めます。

• 投稿先ジャーナル — キャンバス幅が決まります。全一覧は references/journal-specs.md を参照してください。特によく使われる4誌の概要を以下に示します。
• パネルのグリッド — 1x1、1x2、2x2、上段ワイド＋サブパネル、または自由形式の mm 座標。
• カラーパレット — references/color-palettes.md から選び、すべてのパネルで統一して使用します。

ジャーナルの幅／フォント最小値早見表

ジャーナル	1段組	2段組	本文フォントの最小値	備考
Nature	89 mm	183 mm	5 pt	パネルラベルは8 pt
Science	55 mm	120 mm	6 pt	Myriad／Helvetica を推奨
Cell	85または112 mm	174 mm	6 pt	高さは最大225 mm
PNAS	87 mm	180 mm	6 pt	高さ2 mm未満のラベルは不可

ステップ4のバリデーターがこれらの要件を適用します。バリデーターが早い段階で警告できるよう、投稿先ジャーナルは早めに選んでください。

ステップ2：要素を作成する

各パネルは独立した SVG として生成します。一般的なソースは次のとおりです。

• プロット： matplotlib／seaborn を使い、bbox_inches='tight', transparent=True, format='svg' を指定して保存します。ライブラリの選択フローチャートと SciencePlots のレシピについては、figures:plot-styling スキルを参照してください。
• アイコン： figures:transparent-icons スキルを使って、背景が透明な PNG を作成します。
• 模式図： 新しい Python ベースの作業には figures:svg-primitives（自動フィットするボックス、検証済みの矢印、レイヤー化された z 順序）を使用します。手作業で SVG を作成する場合のパターンについては、figures:svg-figure を参照してください。

各要素を作業ディレクトリ（通常は panels/）に保存し、ステップ3で配置します。

ステップ3：図を構成する

コンポーザーは svgutils（MIT ライセンス。uv run --with svgutils）をベースにしています。パネルを正確な mm 座標に配置し、テキストを確認可能な SVG <text> 要素として保持します。

構成方法は2つあります。大半のケースでは scripts/compose.py の Figure ヘルパーを使用し、細かく制御する場合は svgutils.compose を直接使用します。

レシピA：ヘルパー（推奨）

uv run --with svgutils --with lxml python scripts/compose.py panels-config.json -o figure.svg

panels-config.json のスキーマ：

{
  "width_mm": 183,
  "height_mm": 120,
  "journal": "nature",
  "panels": [
    {"id": "A", "src": "panels/spectrum.svg", "x_mm": 0,  "y_mm": 0, "scale": 0.5, "label": "A"},
    {"id": "B", "src": "panels/topomap.svg",  "x_mm": 92, "y_mm": 0, "scale": 0.5, "label": "B"},
    {"id": "C", "src": "panels/timecourse.svg", "x_mm": 0, "y_mm": 60, "scale": 1.0, "label": "C", "width_mm": 183}
  ]
}

パネルラベル（A、B、C）は、各パネルの左上に12 ptの太字サンセリフ体で配置されます。

レシピB：svgutils を直接使用（細かく制御）

from svgutils.compose import Figure, SVG, Panel, Text

fig = Figure(
    "183mm", "120mm",
    Panel(
        SVG("panels/spectrum.svg").scale(0.5),
        Text("A", 5, 15, size=12, weight="bold"),
    ).move(0, 0),
    Panel(
        SVG("panels/topomap.svg").scale(0.5),
        Text("B", 5, 15, size=12, weight="bold"),
    ).move(92, 0),
)
fig.save("figure.svg")

パターン（パネルの拡大縮小、ラベルの配置、スケールバー、マルチパネルグリッドのユーティリティ）については、references/composition-workflow.md を参照してください。

ステップ 4：エクスポート前にフォントを検証する

このステップにより、投稿論文が却下される事態を防げます。次を実行します。

uv run --with lxml python scripts/validate_fonts.py figure.svg --journal nature

バリデーターは、font-size を持つすべての <text> 要素と <tspan> 要素を解析し、累積した変換スタックをたどって最終的な物理寸法での有効なフォントサイズを計算し、ジャーナルの最小サイズを下回るものを報告します。出力は JSON です。

{
  "svg": "figure.svg",
  "journal": "nature",
  "minimum_pt": 5.0,
  "checked_count": 47,
  "skipped_count": 0,
  "issue_count": 1,
  "issues": [
    {
      "text": "Frequency (Hz)",
      "specified_pt": 9.0,
      "effective_pt": 4.5,
      "scale_x": 0.5,
      "scale_y": 0.5,
      "minimum_pt": 5.0,
      "tag_id": ""
    }
  ]
}

skipped_count は、font-size を解決できなかったテキスト要素（CSS クラスセレクター、継承されたスタイル）を数えます。終了コードは、0 が問題なし、1 が問題あり、2 がスクリプトエラー（SVG の形式不正、ファイルの欠落）です。

パネルが原因の場合（その .scale() が小さすぎる場合）、次の 3 つの対処法があります。

1. 小さな文字をそのままにせず、該当パネルを拡大する（他のパネルは縮小します）。
2. 元のプロットのフォントサイズを大きくすることで、パネルのスケールが 0.5 でも条件を満たすようにします（例：元が 12 pt なら、スケール 0.5 で 6 pt となり、Science の最小値 6 pt を満たします）。
3. より大きなキャンバスに切り替える（例：1 カラムから 1.5 カラムに変更します）。

仕組みと根拠の詳細については、references/font-validation.md を参照してください。

ステップ 5：PDF/PNG にエクスポートする

uv run --with cairosvg python scripts/export.py figure.svg --out figure.pdf --dpi 300

export.py は実行時に $PATH 上の Inkscape を検出します。Inkscape がある場合、最も高品質な PDF が生成されます（テキストはテキストのまま保持され、フォントはサブセット化されます）。ない場合、スクリプトは cairosvg にフォールバックし、インストールされていないフォントを使ったテキストがパスに変換されるか、スキップされる可能性があることを stderr の警告で知らせます。

Inkscape のインストール（一度限り、推奨）

brew install inkscape    # macOS
sudo apt install inkscape # Debian/Ubuntu

brew install inkscape は 1 行のコマンドで、初回に約 200 MB の容量が必要です。インストール後はスクリプトが自動的に検出します。cairosvg へのフォールバックは Inkscape がなくても動作しますが、ジャーナル指定のフォントがインストールされていない場合、PDF の品質は低くなります。

キャプションのガイドライン

次の要件を満たす図のキャプションを作成します。

• 簡潔なタイトル（太字、1 文）から始めます。
• 各パネルを説明します：「（A）説明。（B）説明。（C）説明。」
• すべての略語は初出時に定義します（例：「脳波記録法（EEG）」）。
• サンプルサイズ、統計検定、エラーバーの意味を記載します。
• スケールバーがある場合は、その値を記載します。

品質保証

figures:figure-qa エージェントは、構成した SVG を事前に検査し、幾何学的な正確さ、配置、カラーパレットへの準拠、ラベルの読みやすさを確認します。エージェントは内部で validate_fonts.py を実行してフォントサイズを確認するとともに、SVG ブランチのパレットと幾何学的なチェックも行います。

追加リソース

• references/composition-workflow.md — svgutils のパターンと慣用的な使い方
• references/font-validation.md — pt の最小値の仕組み、変換スタックの計算
• references/journal-specs.md — ジャーナルの寸法とフォント規則の一覧
• references/color-palettes.md — 色覚多様性に配慮したパレット（Wong、Okabe-Ito、viridis、Crameri）
• scripts/compose.py — svgutils コンポーザー（CLI + ライブラリ）
• scripts/validate_fonts.py — フォントサイズバリデーター
• scripts/export.py — Inkscape/cairosvg エクスポーター
• examples/two-column-figure.py — 最初から最後まで実行できる例（matplotlib のパネル → 構成 → 検証 → エクスポート）