scientific-visualization

科学的可視化

見た目を最適化する前に、科学的な意味を保持する図を作成してください。普遍的な原則と時代に依存する出版社のルールを分離し、生データと変換を保持し、色を冗長に使用し、プロットのデフォルト設定を信頼するのではなく、納品されたファイルを検査してください。

譲れないガードレール

• 図を良く見せるためにデータを改変、隠蔽、捏造、または選択的に強調しないでください。
• 生の表/画像、除外、欠損値コード、分析コード、正規化、ビニング、画像調整、および乱数シードを保持してください。
• ジャーナルの要件を推測しないでください。正確なジャーナル、記事種別、図の種類、および投稿段階を特定し、その最新の公式ガイダンスを確認してください。
• パレット、DPI 値、形式、または自動レポートが、図をアクセシブルまたはジャーナル準拠にすると主張しないでください。
• 欠損した観測を無言で接続したり、都合の悪い点を抑制したり、詳細が増えたかのように画像をアップサンプリングしたり、結論を誇張するために軸/二重軸を調整したりしないでください。
• インタラクティブな出力と静的な出力は、別個の成果物として維持してください。インタラクティブなホバーは、ラベル、代替テキスト、キーボードアクセス、アクセシブルなデータテーブル、または静的なフォールバックの代わりにはなりません。

欺瞞的なエンコーディングと整合性のチェックについては、references/publication_guidelines.md を参照してください。references/journal_requirements.md は、対象と段階が判明した後にのみ参照してください。

ワークフロー

1. エビデンスと目的地を定義する

以下を記録します。

• 対象読者と媒体: 原稿、ウェブ、スライド、ポスター、補足資料;
• 正確な出版社/ジャーナル、記事種別、投稿段階、および意図する最終的な幅;
• 変数の意味、単位、サンプル/反復の構造、欠損/打ち切り値;
• 推定量と不確実性の定義;
• 変換: フィルタリング、集計、正規化、平滑化、ビン、画像処理;
• ソースデータのパス/識別子と出力の来歴。

要件が不明な場合は、暫定的な一般的な図を作成し、すべての出版社に関わる選択を検証待ちとしてラベル付けしてください。

2. 誠実なエンコーディングを選ぶ

共通スケール上の位置を優先してください。コーディングの前に、以下を確認します。

• 棒/面積: 長さ/面積は基準線から測定されるため、通常はゼロを含めます。
• 点/線: 非ゼロの範囲は有効な場合があります。文脈を示し、断絶を開示してください。
• 不確実性: SD、SE、CI、パーセンタイル、事後分布、またはその他の区間を明示してください。n と反復の単位を述べてください。
• 生の観測: 可能な場合はそれらを示してください。ジッターがカテゴリ/値を不明瞭にしないようにしてください。
• 欠損データ: 欠損、ゼロ、打ち切り、除外を区別してください。ギャップまたは明示的なモデル/補間のスタイルを使用してください。
• 面積/体積: 半径/直径ではなく、面積/体積をスケーリングしてください。装飾的な 3D は避けてください。
• 対数軸: 底/変換をラベル付けし、ゼロ/負の値がどのように扱われるかを宣言してください。
• ビニング/平滑化: エッジ、帯域幅/ウィンドウ、手法、および感度を記録してください。
• 正規化: 式/基準を述べ、比較されるパネル間で範囲を一貫させてください。
• 二重軸: 整列したパネルを優先してください。避けられない場合は、単位を正当化し、見かけの相関を作為的に作り出さないでください。
• 画像: オリジナルを保持し、画像全体の調整を開示し、スケールバーを示し、背景の切り取り/消去を避けてください。

3. アクセシビリティを後付けではなく設計に組み込む

• 色に加えて、マーカー、線種、ハッチング、直接ラベル、またはパネル分離を使用してください。
• データの意味に応じて、定性的、順序的、発散的、または循環的な色を選択してください。
• レンダリングされたサイズで前景/背景のコントラストを監査してください。
• 欠損値と範囲外の値を明示してください。
• 代替テキスト、複雑な図にはより長い説明、およびウェブ配信用の基礎データを提供してください。
• WCAG 2.2 をウェブ向けガイダンスとして扱ってください: 通常テキストは 4.5:1、大きなテキストは 3:1、理解に必要なグラフィカルオブジェクトは 3:1。色だけを手がかりにすることはできません。適用範囲と例外が重要です。

references/color_palettes.md を参照してください。グレースケール画面は有用ですが、完全な色覚またはアクセシビリティのテストではありません。

4. スコープ付きスタイルで実装する

Matplotlib のオブジェクト指向 API と一時的なスタイルコンテキストを使用します。

import matplotlib.pyplot as plt

from style_presets import style_context

with style_context("default", palette_name="okabe_ito_on_white"):
    fig, ax = plt.subplots(
        figsize=(89 / 25.4, 60 / 25.4),
        layout="constrained",
    )
    ax.plot(x, y, marker="o", label="Observed")
    ax.set(xlabel="Time (hours)", ylabel="Response (unit)")
    ax.legend()

layout="constrained" は、カラーバー、ネストされた GridSpec、サブフィギュア、subplot_mosaic に対応しています。その後に tight_layout() を呼び出さないでください。制約付きレイアウトが無効になります。

正確な物理寸法が必要な場合、ページサイズの変更が意図的でない限り、bbox_inches="tight" は使用しないでください。

色の正規化

import matplotlib as mpl

norm = mpl.colors.TwoSlopeNorm(vmin=-2, vcenter=0, vmax=5)
cmap = mpl.colormaps["RdBu_r"].with_extremes(bad="#777777")
image = ax.imshow(values, norm=norm, cmap=cmap, interpolation="nearest")
fig.colorbar(image, ax=ax, label="Change (unit)")

マッピングが科学的な意味と一致する場合に限り、LogNorm、CenteredNorm、SymLogNorm、BoundaryNorm、TwoSlopeNorm を使用します。

Seaborn

Seaborn 0.13.2 では、現行の errorbar API を使用します。

sns.lineplot(
    data=frame,
    x="time",
    y="response",
    hue="treatment",
    style="treatment",
    markers=True,
    errorbar=("ci", 95),
    n_boot=5000,
    seed=20260723,
    ax=ax,
)

Axes レベルの関数はカスタム Matplotlib レイアウトに適しています。Figure レベルの関数は独自の Figure／ファセットを作成します。Seaborn の内部アーティストリストを、安定した API であるかのようにカスタマイズしないでください。

Plotly

• インタラクティブな出力には write_html() を、静的な出力には write_image()／plotly.io.write_images() を使用します。
• Kaleido 1.3.0 には Chrome／Chromium が必要です。Chrome は同梱されなくなりました。
• 現在の静的形式は、PNG、JPEG、WebP、SVG、PDF です。EPS は Kaleido v0 のみで使用できます。
• 非推奨の engine= を渡したり、Orca／plotly.io.kaleido.scope を使用したりしないでください。
• width、height、scale はピクセル数を制御します。scale=3 が必ず「300 DPI」を意味するわけではありません。
• WebGL トレースは、PDF／SVG にラスターコンテンツを埋め込みます。
• 完全オフラインでエクスポートするには、図が MathJax／topojson／タイルを参照する場合、外部アセットをローカルに用意する必要があります。

5. 明示的にエクスポートし、来歴を記録する

from figure_export import export_figure

report = export_figure(
    fig,
    "outputs/figure1",
    formats=["pdf", "png"],
    dpi=600,
    bbox_inches=None,  # preserve figure page dimensions
    provenance={
        "raw_data": "data/source.csv",
        "transformations": ["predeclared QC filter", "group mean"],
        "uncertainty": "95% bootstrap CI; seed 20260723",
        "missing_data": "retained as gaps",
    },
    write_manifest=True,
)

エクスポーターは暗黙の上書きを拒否し、アトミックに書き込み、埋め込みラスターのベクター DPI を維持し、TIFF には LZW を使用します。また、PDF／PS では Type 42 フォントを使用できます。科学的な内容や出版社の受け入れ要件は検証しません。

編集可能なフォントについて：

• PDF／PS の Type 42 は TrueType フォントを埋め込みます。
• svg.fonttype="none" はテキストを編集・検索可能な状態に保ちますが、フォントは埋め込みません。表示はインストール済みフォントに依存します。
• svg.fonttype="path" はグリフの外観をパスとして保持しますが、テキストの編集・検索はできなくなります。

透明度が必要でない限り、不透明な背景色を明示的に指定してください。別の背景色に重ねると、見かけのコントラストが変わります。

6. 検査、比較、レビューを行う

1. ファイルのメタデータを検査します。
2. パレットのコントラストとグレースケールでの分離を監査します。
3. 日付付きの出版社スナップショットと比較します。
4. 原稿／ウェブでの最終的な使用状況に合わせたサイズで表示します。
5. フォント、埋め込みラスター、クリッピング、凡例、スケールバー、画像の完全性、キャプション、代替テキスト、ソースデータを手動で確認します。
6. アップロード直前に、投稿先ジャーナルの最新ページを再確認します。

固定スナップショット

例とスモークテストでは、2026-07-23 時点の直接依存関係のバージョンを固定して使用します。

uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  --with "seaborn==0.13.2" \
  --with "plotly==6.9.0" \
  --with "kaleido==1.3.0" \
  --with "pillow==12.3.0" \
  --with "pypdf==6.14.2" \
  python your_figure.py

これは日付付きの直接依存関係のスナップショットであり、推移的依存関係のロックではありません。正確な再実行にはプロジェクトの uv ロックを使用してください。このスキルには、意図的に依存関係ロックを同梱していません。

同梱 CLI

すべてのヘルパーは決定的で、ネットワークを使用せず、処理範囲に上限があり、該当する場合はシンボリックリンクの入力／出力先を拒否します。また、--force が明示されない限り、上書きを拒否します。

ラスター／ベクターのメタデータを検査する

uv run --isolated --no-project --python 3.13 \
  --with "pillow==12.3.0" \
  python scripts/image_metadata.py figure.tiff \
  --format tiff --mode RGB --min-dpi 300 --target-width-mm 85 \
  --alpha-policy forbid

ラスター画像（Pillow）、SVG、PDF（pypdf）、EPS／PS に対応しています。寸法、DPI／実効 DPI、モード、アルファ、ICC の有無、圧縮方式、ページサイズ、および PDF の最初のページに含まれるフォントリソース（保守的な判定）を報告します。ベクターコンテナー内の埋め込みラスターをすべて検査するわけではありません。

パレットのコントラストとグレースケールを監査する

uv run --isolated --no-project --python 3.13 \
  python scripts/palette_audit.py \
  --palette okabe_ito_on_white \
  --background FFFFFF \
  --role graphical

WCAG sRGB コントラストの正確な値と、色ごとの CIE L* グレースケールスクリーニングを報告します。グレースケールのしきい値はヒューリスティックであり、標準ではありません。

出版社向けエクスポートを計画／スクリーニングする

uv run --isolated --no-project --python 3.13 \
  python scripts/export_plan.py \
  --publisher nature \
  --figure-type combination \
  --width single \
  --phase final

機械可読プロパティをスクリーニングするには、--input figure.pdf を追加します。プロファイルは 2026-07-23 に取得した公式ソースのスナップショットであり、自動的な準拠ルールではありません。

スタイルをプレビューする

uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  python scripts/style_preview.py \
  --output outputs/style-preview \
  --style default \
  --palette okabe_ito_on_white \
  --formats png,svg

スタイルを検査／書き込みし、エクスポートをスモークテストする

uv run --isolated --no-project --python 3.13 \
  python scripts/style_presets.py --list
uv run --isolated --no-project --python 3.13 \
  python scripts/style_presets.py --show nature
uv run --isolated --no-project --python 3.13 \
  --with "matplotlib==3.11.1" \
  python scripts/figure_export.py --demo outputs/export-smoke --manifest

アセット

• assets/publication.mplstyle：一般的な印刷向けの基本スタイルです。
• assets/nature.mplstyle：Natureの代表的なビジュアルを参考にした、日付付きの基本スタイルです。適合性を保証するプリセットではありません。
• assets/presentation.mplstyle：投影表示向けに大きめのスタイルです。
• assets/color_palettes.py：メタデータ付きで、Okabe-ItoとPaul Tolのカラー値をインポートできます。
• assets/publisher_profiles.json：日付付きで、機械可読な計画用スナップショットです。

Matplotlibのスタイルファイルでは、.mplstyleの解析時に#がコメントの開始として扱われるため、16進カラーコードから#を省略しています。

参考資料

• references/publication_guidelines.md：研究公正、誤解を招くエンコーディング、アクセシビリティ、静的／インタラクティブ出力について説明します。
• references/color_palettes.md：パレットの意味、正確な値、WCAGコントラスト、グレースケールの注意点、カラー管理について説明します。
• references/journal_requirements.md：段階ごとの出版社公式スナップショットです。
• references/matplotlib_examples.md：最新の、実行可能なMatplotlib／Seaborn／Plotlyのパターンです。
• references/sources.md：公式URL、日付、バージョン、調査の根拠です。

最終確認チェックリスト

• 生データ／画像と変換コードが保持されています。
• 欠損値、除外項目、ビン、正規化、不確実性が明示されています。
• ベースライン、スケール、範囲、面積／体積によるエンコーディングが適切です。
• 色に冗長性があり、レンダリング後のコントラストが確認されています。
• 該当する場合、図にアクセシブルな説明／データの代替手段があります。
• エクスポート後に、物理寸法、DPI、形式、フォント、透過性、ファイルサイズを確認しました。
• 対象のジャーナルと段階に適用される出版社の規則を確認しました。
• 自動生成されたレポートを、科学的妥当性、アクセシビリティ、適合性の認証として提示していません。

関連スキル

• matplotlib：細かなカスタマイズができる低レベルのプロットライブラリです。
• academic-plotting：研究のコンテキストに基づき、ML論文向けの出版品質の図を生成します。
• seaborn：pandasと連携する統計可視化ツールです。