publication-chart-skill

Publication Chart Skill

目的

このスキルを使うと、エンドツーエンドのワークフローで研究成果を出版品質の図表に仕上げられます。

主な制作スタック：

• 図には pubfig
• 出版用の表には pubtab

このスキルでは、納品までの全工程を扱います。

1. 科学的な伝達目標を理解する、
2. 適切な成果物の種類を選ぶ、
3. 作業内容に応じて pubfig、pubtab、または両方を使い分ける、
4. 実行可能な具体的な手順を生成する、
5. 論文にそのまま使えるアセットを書き出す、
6. 出版に向けた品質チェックを実施する、
7. 対象を絞った修正案を提示する。

このスキルを使用する場面

次のような依頼には、このスキルを使ってください。

• 「出版品質の図を作成して」
• 「この結果に適したグラフを選んで」
• 「この結果を論文にそのまま使える図にして」
• 「ベンチマーク／アブレーション／キャリブレーション／フォレスト／ヒートマップ／散布／折れ線／棒グラフを作成して」
• 「Excelからベンチマーク／付録／アブレーション用の表を作成して」
• 「このExcel表を出版用のLaTeXに変換して」
• 「結果セクション用に、要約図と対応する表を1つずつ作成して」
• 「この科学論文の図表をレビューして改善して」
• 「すでにある見栄えの悪いグラフ／スクリーンショット／下書きのプロットを、出版品質に仕上げて」
• 「論文用の図のパネルを書き出して」

このスキルを使用しない場面

主な作業が次のいずれかである場合は、このスキルを使用しないでください。

• 論文の本文執筆、
• 成果物のデザインを伴わない統計的検定、
• 出版用の納品物を必要としない生の探索的分析、
• 図表の内容が固まる前にFigmaを中心にレイアウトを作成する作業。

図表の内容がすでに整っている場合に、シンプルな複合図の組み立てを行うには、references/composite-assembly.md のオプションのセカンダリーワークフローを使用してください。

基本契約

入力

次の情報の一部またはすべてを想定します。

• 科学的な伝達目標、
• 利用可能なデータの形式、
• 投稿先やスタイルの制約、
• 成果物が図、表、または両方を含むかどうか、
• コード、スプレッドシート、.tex、スクリーンショット、下書きのプロットなど、任意の既存アセット、
• ユーザーが必要としているのが初稿、出版可能な成果物、またはレビュー／修正のどれか。

出力

最低限、次の内容を含む有用な出力を作成します。

• 推奨する図表の形式、
• 推奨する pubfig／pubtab の使用方法、
• 最小限の実行可能なコードスニペットまたはCLIコマンド、
• 明示的な書き出しファイル名と形式、
• 出版に向けた品質チェックの概要、
• 必要に応じた修正計画。

デフォルトのワークフロー

0. 環境と成果物の状態を確認する

何かを生成する前に、次の点を確認します。

• pubfig または pubtab が実際に利用可能か
• ユーザーがすでにコード／スプレッドシート／.tex／スクリーンショットを用意しているか
• 成果物が新規作成か、既存のものの修正か
• 結果に正確な値、素早い視覚的な把握、またはその両方が必要か

作業に役立つ、最小限の環境チェックを優先します。同梱のヘルパースクリプトが利用可能な場合は、まず次を実行します。

• python3 scripts/ensure_publication_tooling.py --require pubfig --json
• python3 scripts/ensure_publication_tooling.py --require pubtab --json

必要に応じて、次のような手動チェックを行ってもかまいません。

• python -c "import pubfig; print(pubfig.__version__)"
• python -c "import pubtab; print(pubtab.__version__)"
• pubtab --help

結果は 利用可能 または 不足 と明確に報告します。

依存関係が不足しており、タスクで実行可能な状態が必要な場合は、次のようにします。

• デフォルトで自動インストールします。
• 適当なグローバルインタープリターを推測するのではなく、ユーザーが現在使用している環境を優先します。
• スクリプトが存在する場合は、デフォルトの同梱手段として python3 scripts/ensure_publication_tooling.py --require ... を使用します。
• ヘルパーに、アクティブなインタープリターに対して uv と python -m pip のどちらを使うか選ばせます。
• インストール後に利用可能かどうかを再確認します。
• 確認が済んでから成果物のワークフローに進みます。

同等の具体的なコマンドは次のとおりです。

• python3 scripts/ensure_publication_tooling.py --require pubfig
• python3 scripts/ensure_publication_tooling.py --require pubtab
• uv pip install pubfig
• uv pip install pubtab
• python -m pip install pubfig
• python -m pip install pubtab

自動インストールに失敗した場合は、失敗の内容を正確に報告し、そのうえで可能な範囲で代替手段を講じます。

環境の完全な監査が終わるまで作業を止めないでください。

1. タスクを分類する

次の観点で依頼を分類します。

• 成果物の種類：図／表／図表を組み合わせた成果物
• 完成度：探索的なドラフト／出版可能な品質での生成／既存の成果物の修正
• 構成：単一パネル／複数パネル／図と表のパッケージ
• エビデンスの用途：パターンの把握／正確な値の参照／その両方

伝えるべき内容が明確になる前に、作図コードに着手しないでください。

研究結果を作図する前に、エビデンスの条件を明確にします。

• 主な科学的主張
• 分析単位
• 主な指標と、その指標の方向性
• 繰り返しの行が独立しているかどうか
• 欠損セルや不完全な比較ブロック
• エラーバーの根拠：被験者、被験者とタスクの組み合わせ、フォールド、シード、実行、またはブートストラップサンプル
• 正確な値を補足表に掲載する必要があるか
• 現在のエビデンスで優位性や有意性を主張できるか

これらが不明確な場合は、質問するか、監査に基づく提案を提示してください。未解決のまま、完成度の高い図を作成してはいけません。分析単位、欠損セルの扱い、またはエラーバーの根拠が確定していない状態で、論文にそのまま使える図を作成しないでください。

2. 表現形式を選択する

目新しさや見た目の華やかさではなく、科学的な主張に基づいて表現形式を選択してください。

一般的な形式：

• 比較 — グループ化散布図、棒グラフ、折れ線比較、ベンチマークの要約、補足表
• アブレーション — グループ化比較、ダンベルチャート、ペア比較、コンパクトな表
• 分布 — 箱ひげ図、バイオリンプロット、レインクラウドプロット、ヒストグラム、密度プロット、ECDF、QQプロット
• 関係性 — 散布図、バブルチャート、contour2d、hexbin
• 傾向 — 折れ線グラフ、面グラフ
• 評価／診断 — キャリブレーション、ROC、PR、Bland–Altman、フォレストプロット、ボルケーノプロット
• 構成／階層 — UpSet、積み上げ比率、ドーナツチャート、放射状階層、円形グループ化棒グラフまたは積み上げ棒グラフ
• 表 — ベンチマーク表、アブレーション表、データセットの要約、付録表、エラーの内訳

安易なデフォルトは避けてください：

• 正確な比較が重要で、棒グラフや表のほうが明確な場合は、円グラフ／ドーナツチャートを避けてください。
• 比較対象が真にプロファイル型で、項目数が少ない場合を除き、レーダーチャートを避けてください。
• 装飾目的だけの3D表現、装飾的なグラデーション、情報を詰め込みすぎた凡例を避けてください。
• 論文の表のほうが根拠を明確に伝えられる場合は、すべての結果を図に押し込まないでください。

依頼が曖昧な場合は、成果物がどの科学的主張を裏付けるものなのかを明示してください。

3. ツールチェーンに対応付ける

デフォルトの対応付け：

• 図 → pubfig
• 表 → pubtab
• 複合成果物 → 両方を使い、それぞれの成果物に異なる役割を持たせる

ツールの役割：

• pubfig は、科学的なプロットの作成と論文掲載用のエクスポートに使用する、デフォルトの図作成エンジンです。
• pubtab は、Excel ↔ LaTeX のワークフロー、プレビュー、論文掲載用の表のエクスポートに使用する、デフォルトの表作成エンジンです。
• Figma／複合図の組み立ては、複数パネルの仕上げに使用する任意の二次分岐です。

経路の選択ルール：

• pubfig で図を生成する場合は、Pythonを優先してください。
• ファイルベースのタスクで pubtab を使う場合は、CLIを優先してください。
• タスクがすでにノートブックまたはスクリプト化されたパイプライン内にある場合は、pubtab にPythonを優先してください。
• 複合的な依頼では、図と表の役割を分けてください。

4. 具体的な成果物の指示を作成する

まず、制作に使える最小限の成果物を優先してください：

• pubfig 用の最小限の実行可能な Python、または
• pubtab 用の最小限の CLI／Python

その後、必要性がある場合に限り、掲載用のパラメーターを追加してください：

• ラベル、キャプション、幅、エクスポート形式、バックエンド、プレビュー、パネルのパッケージ化、複合レイアウト。

ファイル名と拡張子は明示してください。

適切なデフォルト：

• 図：pubfig の呼び出しを1回 + save_figure(...) を1回
• 複数の図の出力：batch_export(...)
• 表：pubtab xlsx2tex ... または pubtab.preview ... を1回
• 複合的な依頼：図の経路を1つ、表の経路を1つ、明確に分けて提示

5. 納品条件を定義する

可能な場合は、すべての回答で以下を明示してください：

• 成果物が裏付ける主張
• pubfig と pubtab でそれぞれ処理する部分
• 出力ファイル名
• 出力形式
• 成果物がドラフト／最終版／改訂版のいずれか
• ユーザー提供のデータや原稿の文脈がまだ必要かどうか

6. 掲載品質を確認する

生成後に、以下を確認してください：

• タイトルと凡例の情報量
• 軸ラベルと単位
• カテゴリの並び順とベースラインの明確さ
• 色のアクセシビリティとグレースケールでの見やすさ
• フォントと線の太さの一貫性
• キャプションの完成度
• 縮小時の図表の読みやすさ
• 複数パネルの図におけるパネル間の一貫性
• 幅、混雑、注釈過多など、掲載先に適合するかどうかの問題

QAの結果は具体的にしてください。理由を示さずに「見やすくなりました」とだけ述べないでください。

7. 改訂する

結果が不十分な場合は、次のような具体的な変更を加えて改訂してください：

• グラフ形式を切り替える
• チャートジャンクを取り除く
• カテゴリの順序を変更する
• 正確な値を表に移す
• 混み合ったパネルを分割する
• キャプションを追加または簡潔にする
• エクスポート幅を変更する
• 成果物の優先順位を図から表に切り替える

依存関係が不足している場合の動作

pubfig または pubtab が利用できない場合：

• すぐに失敗させないでください。
• まず、アクティブな環境への自動インストールを試みてください。
• 同梱スクリプトが存在する場合は、python3 scripts/ensure_publication_tooling.py --require ... を優先してください。
• 不足している依存関係を明示してください。
• 使用するインストールコマンドまたはヘルパー経由の方法を明示してください。
• インストール後に利用可能か再確認してください。
• インストールに成功した場合は、実行可能なワークフローを続けてください。
• インストールに失敗した場合は、設計・仕様策定のワークフローに切り替えてください。
• 擬似コードまたは実行案のコマンドを提示してください。
• 推奨する図表の構成を維持してください。
• QA と修正のガイダンスも提示してください。

複合図版の作成ルール

複合図版や Figma での作成は二次的な選択肢として扱ってください。

• ユーザーが論文用のマルチパネル図を明示的に希望する場合、または
• パネル単位のエクスポートやレイアウトの仕上げが本当に必要な場合に使用してください。

単純な図の作成を、既定で複合図版や Figma のワークフローに拡張しないでください。

出力スタイルのルール

• 実装にそのまま使える出力を優先してください。
• グラフや表を選んだ理由を簡潔に説明してから、実行可能な手順を示してください。
• 実行が重要な場合は、pubfig: available/missing、pubtab: available/missing のような環境状況の簡潔なブロックを含めてください。
• 依存関係が不足している場合は、正確なヘルパーコマンドまたはインストールコマンドを示し、インストールを実行して、インストール後の状況を報告してください。
• 表のほうが図より適している場合は、そのことを明示してください。
• 図のほうが表より適している場合は、そのことを明示してください。
• 両方が必要な場合は、それぞれ異なる伝達上の役割を割り当ててください。
• 修正のガイダンスは、実行可能で検証可能な内容にしてください。

推奨する回答の構成

このスキルを活用した優れた回答は、通常、次の 6 部構成です。

1. 成果物の選択 — 図／表／両方の組み合わせと、その理由
2. ツールの使用方法 — pubfig、pubtab、または両方
3. 最小限の実装 — 実行可能なコードまたは CLI
4. エクスポート計画 — ファイル名、形式、幅、バックエンド、プレビューの選択
5. 投稿前の QA — 論文投稿前に確認する項目
6. 修正計画 — 現在の成果物に改善が必要な場合の変更内容

リソース

必要に応じて、以下を参照してください。

• references/workflow.md — エンドツーエンドの判断手順と成果物の要件
• references/chart-selection.md — タスクに応じたグラフの選択と避けるべきパターン
• references/execution-and-verification.md — 環境の確認、強制インストールの動作、実行可能な検証
• scripts/ensure_publication_tooling.py — pubfig／pubtab 用の環境確認・自動インストールヘルパー
• references/pubfig-recipes.md — 図の最短実用パターンとエクスポート方法
• references/pubtab-recipes.md — 表の最短実用手順とバックエンドのガイダンス
• references/source-guides/pubfig-architecture.md — ソースに基づくパッケージ構成と図の生成範囲
• references/source-guides/pubfig-api-map.md — __init__.py に基づく安定した公開 pubfig API とグラフファミリーの一覧
• references/source-guides/pubfig-export-flow.md — ソースに基づく図のエクスポート、論文用サイズ、パネルのエクスポート手順
• references/source-guides/pubtab-architecture.md — ソースに基づくパッケージ構成と順方向・逆方向の変換アーキテクチャ
• references/source-guides/pubtab-cli-api-flow.md — CLI から API への制御フローとバッチ／シートの動作
• references/source-guides/pubtab-backend-and-preview.md — バックエンド／テーマの分離と、実際のプレビューのコンパイルパイプライン
• references/publication-qa-checklist.md — 図表の QA チェックリスト
• references/composite-assembly.md — オプションのマルチパネル図と Figma の分岐

プロンプト形式の例については、examples/ を参照してください。