matplotlib

Matplotlib

概要

Matplotlib は、静的、アニメーション、インタラクティブなプロットを作成するための、Python の基盤となる可視化ライブラリです。このスキルでは、pyplot インターフェース（MATLAB 形式）とオブジェクト指向 API（Figure/Axes）の両方を取り上げ、出版品質の可視化を作成するためのベストプラクティスを含め、Matplotlib を効果的に使用する方法を説明します。

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

次のような場合に、このスキルを使用してください。

• あらゆる種類のプロットやグラフ（折れ線、散布図、棒グラフ、ヒストグラム、ヒートマップ、等高線図など）を作成する
• 科学的または統計的な可視化を生成する
• プロットの外観（色、スタイル、ラベル、凡例）をカスタマイズする
• サブプロットを使って複数パネルの図を作成する
• 可視化をさまざまな形式（PNG、PDF、SVG など）でエクスポートする
• インタラクティブなプロットやアニメーションを作成する
• 3D 可視化を扱う
• Jupyter ノートブックや GUI アプリケーションにプロットを組み込む

セットアップ

プロジェクトで使用する場合は、uv で Matplotlib をインストールします。

uv add matplotlib

ノートブックでのインタラクティブ機能を有効にする場合：

uv add matplotlib ipympl

次に、Jupyter で %matplotlib widget または %matplotlib ipympl を使ってウィジェットバックエンドを有効にします。

Matplotlib 3.10 には Python 3.10 以降と NumPy 1.23 以降が必要です。非インタラクティブなファイル出力には、Agg、PDF、SVG などのバックエンドを使用できます。GUI ウィンドウの場合、Matplotlib は利用可能なバックエンドを自動選択します。uv で管理されている Python で TkAgg が動作しない場合は、uv self update と uv python upgrade --reinstall で uv と Python ビルドを更新するか、uv add pyside6 で Qt バックエンドをインストールしてください。

基本概念

Matplotlib の階層構造

Matplotlib は、オブジェクトの階層構造を使用します。

1. Figure - すべてのプロット要素を含む最上位のコンテナー
2. Axes - データを表示する実際のプロット領域（1 つの Figure に複数の Axes を含めることができます）
3. Artist - 図上に表示されるすべての要素（線、テキスト、目盛りなど）
4. Axis - 目盛りとラベルを扱う数直線オブジェクト（x 軸、y 軸）

2 つのインターフェース

1. pyplot インターフェース（暗黙的、MATLAB 形式）

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()

• 手早くシンプルなプロットを作成するのに便利です
• 状態を自動的に保持します
• インタラクティブな作業やシンプルなスクリプトに適しています

2. オブジェクト指向インターフェース（明示的）

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()

• ほとんどの用途で推奨されます
• Figure と Axes をより明示的に制御できます
• 複数のサブプロットを含む複雑な図に適しています
• 保守やデバッグが容易です

一般的なワークフロー

1. 基本的なプロットの作成

単一プロットのワークフロー：

import matplotlib.pyplot as plt
import numpy as np

# Create figure and axes (OO interface - RECOMMENDED)
fig, ax = plt.subplots(figsize=(10, 6))

# Generate and plot data
x = np.linspace(0, 2*np.pi, 100)
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')

# Customize
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Trigonometric Functions')
ax.legend()
ax.grid(True, alpha=0.3)

# Save and/or display
fig.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()

2. 複数のサブプロット

サブプロットのレイアウトを作成する：

# Method 1: Regular grid
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
axes[0, 0].plot(x, y1)
axes[0, 1].scatter(x, y2)
axes[1, 0].bar(categories, values)
axes[1, 1].hist(data, bins=30)

# Method 2: Mosaic layout (more flexible)
fig, axes = plt.subplot_mosaic([['left', 'right_top'],
                                 ['left', 'right_bottom']],
                                figsize=(10, 8))
axes['left'].plot(x, y)
axes['right_top'].scatter(x, y)
axes['right_bottom'].hist(data)

# Method 3: GridSpec (maximum control)
from matplotlib.gridspec import GridSpec
fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig)
ax1 = fig.add_subplot(gs[0, :])  # Top row, all columns
ax2 = fig.add_subplot(gs[1:, 0])  # Bottom two rows, first column
ax3 = fig.add_subplot(gs[1:, 1:])  # Bottom two rows, last two columns

3. プロットの種類と用途

折れ線グラフ - 時系列、連続データ、傾向

ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')

散布図 - 変数間の関係、相関

ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')

棒グラフ - カテゴリ間の比較

ax.bar(categories, values, color='steelblue', edgecolor='black')
# For horizontal bars:
ax.barh(categories, values)

ヒストグラム - 分布

ax.hist(data, bins=30, edgecolor='black', alpha=0.7)

ヒートマップ - 行列データ、相関

im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)

等高線図 - 2D 平面上の 3D データ

contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)

箱ひげ図 - 統計的分布

ax.boxplot([data1, data2, data3], tick_labels=['A', 'B', 'C'])

バイオリンプロット - 分布密度

ax.violinplot([data1, data2, data3], positions=[1, 2, 3])

プロットの種類やバリエーションの詳しい例については、references/plot_types.md を参照してください。

4. スタイルとカスタマイズ

色の指定方法：

• 名前付きの色：'red'、'blue'、'steelblue'
• 16 進コード：'#FF5733'
• RGB タプル：(0.1, 0.2, 0.3)
• カラーマップ：cmap='viridis'、cmap='plasma'、cmap='coolwarm'

スタイルシートの使用：

plt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style
# Available styles: 'ggplot', 'bmh', 'fivethirtyeight', etc.
print(plt.style.available)  # List all available styles

rcParams によるカスタマイズ：

plt.rcParams['font.size'] = 12
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['axes.titlesize'] = 16
plt.rcParams['xtick.labelsize'] = 10
plt.rcParams['ytick.labelsize'] = 10
plt.rcParams['legend.fontsize'] = 12
plt.rcParams['figure.titlesize'] = 18

テキストと注釈：

ax.text(x, y, 'annotation', fontsize=12, ha='center')
ax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),
            arrowprops=dict(arrowstyle='->', color='red'))

スタイルの詳細なオプションやカラーマップのガイドラインについては、references/styling_guide.md を参照してください。

5. 図の保存

さまざまな形式へのエクスポート：

# High-resolution PNG for presentations/papers
fig.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

# Vector format for publications (scalable)
fig.savefig('figure.pdf', bbox_inches='tight')
fig.savefig('figure.svg', bbox_inches='tight')

# Transparent background
fig.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

重要なパラメーター：

• dpi：解像度（出版用は 300、Web 用は 150、画面用は 72）
• bbox_inches='tight'：余分な余白を削除します
• facecolor='white'：背景を白にします（透明テーマで便利です）
• transparent=True：背景を透明にします

6. 3D プロットの操作

fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(111, projection='3d')

# Surface plot
ax.plot_surface(X, Y, Z, cmap='viridis')

# 3D scatter
ax.scatter(x, y, z, c=colors, marker='o')

# 3D line plot
ax.plot(x, y, z, linewidth=2)

# Labels
ax.set_xlabel('X Label')
ax.set_ylabel('Y Label')
ax.set_zlabel('Z Label')

ベストプラクティス

1. インターフェースの選択

• 本番環境のコードではオブジェクト指向インターフェース（fig, ax = plt.subplots()）を使用します
• pyplot インターフェースは、すばやく対話的に試す場合にのみ使用します
• 暗黙の状態に頼らず、常に明示的に図を作成します

2. 図のサイズと DPI

• 作成時に figsize を設定します：fig, ax = plt.subplots(figsize=(10, 6))
• 出力媒体に適した DPI を使用します：
  • 画面／ノートブック：72-100 dpi
  • Web：150 dpi
  • 印刷／出版物：300 dpi

3. レイアウト管理

• 要素が重ならないように、constrained_layout=True または tight_layout() を使用します
• 自動で間隔を調整するため、fig, ax = plt.subplots(constrained_layout=True) の使用をおすすめします

4. カラーマップの選択

• 逐次型（viridis、plasma、inferno）：一貫した推移を持つ順序データ
• 発散型（coolwarm、RdBu）：意味のある中心点（例：ゼロ）があるデータ
• 定性型（tab10、Set3）：カテゴリ／名義データ
• レインボーカラーマップ（jet）は知覚的に均一ではないため、使用を避けます

5. アクセシビリティ

• 色覚に配慮したカラーマップ（viridis、cividis）を使用します
• 棒グラフでは、色に加えてパターン／ハッチングを追加します
• 要素間に十分なコントラストを確保します
• 説明的なラベルと凡例を含めます

6. パフォーマンス

• 大規模なデータセットでは、プロットの呼び出しに rasterized=True を使用してファイルサイズを削減します
• プロットの前に、適切なデータ削減（例：密度の高い時系列データのダウンサンプリング）を行います
• アニメーションでは、パフォーマンス向上のためにブリッティングを使用します

7. コードの整理

# Good practice: Clear structure
def create_analysis_plot(data, title):
    """Create standardized analysis plot."""
    fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)

    # Plot data
    ax.plot(data['x'], data['y'], linewidth=2)

    # Customize
    ax.set_xlabel('X Axis Label', fontsize=12)
    ax.set_ylabel('Y Axis Label', fontsize=12)
    ax.set_title(title, fontsize=14, fontweight='bold')
    ax.grid(True, alpha=0.3)

    return fig, ax

# Use the function
fig, ax = create_analysis_plot(my_data, 'My Analysis')
fig.savefig('analysis.png', dpi=300, bbox_inches='tight')

クイックリファレンススクリプト

このスキルには、scripts/ ディレクトリにヘルパースクリプトが含まれています：

plot_template.py

ベストプラクティスに沿って、さまざまな種類のプロットを示すテンプレートスクリプトです。新しい可視化を作成する際の出発点として使用してください。

使用方法：

uv run python scripts/plot_template.py

style_configurator.py

matplotlib のスタイル設定を対話的に行い、カスタムスタイルシートを生成するユーティリティです。

使用方法：

uv run python scripts/style_configurator.py

詳細なリファレンス

詳しい情報については、リファレンスドキュメントを参照してください：

• references/plot_types.md - コード例とユースケースを含む、プロットの種類の完全なカタログ
• references/styling_guide.md - スタイル設定、カラーマップ、カスタマイズの詳細
• references/api_reference.md - コアクラスとメソッドのリファレンス
• references/common_issues.md - よくある問題のトラブルシューティングガイド

他のツールとの連携

Matplotlib は次のツールと相性よく連携します：

• NumPy/Pandas - 配列や DataFrame から直接プロット
• Seaborn - matplotlib を基盤とする高水準の統計的可視化
• Jupyter - %matplotlib inline または %matplotlib widget を使った対話型プロット
• GUI フレームワーク - Tkinter、Qt、wxPython アプリケーションへの埋め込み

よくある注意点

1. 要素の重なり：constrained_layout=True または tight_layout() を使用します
2. 状態の混乱：pyplot の状態マシンに関する問題を避けるため、OO インターフェースを使用します
3. 図を多数作成した場合のメモリの問題：plt.close(fig) で図を明示的に閉じます
4. フォントの警告：フォントをインストールするか、plt.rcParams['font.sans-serif'] で警告を抑制します
5. DPI の混同：figsize の単位はピクセルではなくインチです：pixels = dpi * inches

追加リソース

• 公式ドキュメント：https://matplotlib.org/
• ギャラリー：https://matplotlib.org/stable/gallery/index.html
• チートシート：https://matplotlib.org/cheatsheets/
• チュートリアル：https://matplotlib.org/stable/tutorials/index.html

エージェントの作業手順

1. 環境を確認します。 データソース、各図で伝えるべき内容、対象媒体（論文、ポスター、スライド）を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果が変わる値については、推測せずに質問します。
3. まず小規模に実行します。 最終サイズで図を1つ描画し、全体を作成する前に読みやすさを確認します。
4. 上記の指示と参考資料を使って、タスク全体を実行します。
5. 結果を検証します。 軸、単位、エラーバーにラベルと定義があり、色が色覚多様性に配慮され、数値が元データと一致していることを確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を伝えます。

発生した場合	対応
最終サイズで文字が読めない	フォントサイズを大きくするか、パネルを簡略化します。文字を小さくしてはいけません。
この手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適切に対応してユーザーに伝えます。APIを捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に前提を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 図の見栄えをよくするためにデータを改変してはいけません。画像の調整は一律に適用し、その内容を開示します。
• ここに記載されたバージョン固有の情報は古い可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 金銭が発生する、共有 GPU やクラウドの利用枠を消費する、個人データまたは患者データを扱う、あるいは取り消せない操作を行う場合は、事前に確認します。

関連スキル

• seaborn：pandas と連携した統計的な可視化です。
• scientific-visualization：Matplotlib、Seaborn、Plotly を使用して、正確でアクセシブルな、出版に適した科学図を作成し、監査します。
• scientific-schematics：自然言語プロンプトを使い、OpenRouter 経由で Nano Banana 2 を利用して、出版向けのスタイルの科学図をラスター PNG 画像として生成します。th…