plotly

Plotly

インタラクティブで出版品質のビジュアライゼーションを作成するための Python グラフライブラリで、40 種類以上のチャートタイプをサポートしています。

使用すべき場面

• ホバー、ズーム、パン、または Web 埋め込みを備えたインタラクティブなチャートが必要な場合。
• 豊富なインタラクションが役立つダッシュボード、探索的 분석ノートブック、またはプレゼンテーションを構築している場合。
• 同じビジュアライゼーションタスクに対して Plotly Express と Graph Objects のどちらを使うかを選択したい場合。

クイックスタート

Plotly をインストールします:

uv pip install plotly

Plotly Express（高レベル API）を使った基本的な使用方法:

import plotly.express as px
import pandas as pd

df = pd.DataFrame({
    'x': [1, 2, 3, 4],
    'y': [10, 11, 12, 13]
})

fig = px.scatter(df, x='x', y='y', title='My First Plot')
fig.show()

API の選択

Plotly Express（px）を使う

適切なデフォルト設定で、迅速かつ標準的なビジュアライゼーションを行う場合:

• pandas の DataFrame を扱う
• 一般的なチャートタイプ（散布図、折れ線、棒、ヒストグラムなど）を作成する
• 自動的な色エンコーディングと凡例が必要
• 最小限のコード（1〜5 行）で済ませたい

完全なガイドについては reference/plotly-express.md を参照してください。

Graph Objects（go）を使う

細かい制御とカスタムビジュアライゼーションを行う場合:

• Plotly Express にないチャートタイプ（3D メッシュ、等値面、複雑な金融チャート）
• 複数のトレースからなる複雑な図をゼロから構築する
• 個々のコンポーネントを正確に制御する必要がある
• カスタム図形やアノテーションを使った特殊なビジュアライゼーションを作成する

完全なガイドについては reference/graph-objects.md を参照してください。

注意: Plotly Express は graph objects の Figure を返すため、両方のアプローチを組み合わせることができます:

fig = px.scatter(df, x='x', y='y')
fig.update_layout(title='Custom Title')  # Use go methods on px figure
fig.add_hline(y=10)                     # Add shapes

主な機能

1. チャートタイプ

Plotly はカテゴリ別に整理された 40 種類以上のチャートタイプをサポートしています:

基本チャート: 散布図、折れ線、棒、円、エリア、バブル

統計チャート: ヒストグラム、箱ひげ図、バイオリン、分布、エラーバー

科学チャート: ヒートマップ、等高線、三成分、画像表示

金融チャート: ローソク足、OHLC、ウォーターフォール、ファネル、時系列

地図: 散布地図、コロプレス、密度地図（地理的ビジュアライゼーション）

3D チャート: scatter3d、サーフェス、メッシュ、コーン、ボリューム

特殊チャート: サンバースト、ツリーマップ、サンキー、平行座標、ゲージ

すべてのチャートタイプの詳細な例と使用方法については reference/chart-types.md を参照してください。

2. レイアウトとスタイリング

サブプロット: 軸を共有する複数プロットの図を作成します:

from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(rows=2, cols=2, subplot_titles=('A', 'B', 'C', 'D'))
fig.add_trace(go.Scatter(x=[1, 2], y=[3, 4]), row=1, col=1)

テンプレート: 統一されたスタイリングを適用します:

fig = px.scatter(df, x='x', y='y', template='plotly_dark')
# Built-in: plotly_white, plotly_dark, ggplot2, seaborn, simple_white

カスタマイズ: 外観のあらゆる側面を制御します:

• 色（離散シーケンス、連続スケール）
• フォントとテキスト
• 軸（範囲、目盛り、グリッド）
• 凡例
• 余白とサイズ
• アノテーションと図形

完全なレイアウトとスタイリングのオプションについては reference/layouts-styling.md を参照してください。

3. インタラクティブ性

組み込みのインタラクティブ機能:

• カスタマイズ可能なデータを持つホバーツールチップ
• パンとズーム
• 凡例の切り替え
• ボックス/投げ縄選択
• 時系列用の rangeslider
• ボタンとドロップダウン
• アニメーション

# Custom hover template
fig.update_traces(
    hovertemplate='<b>%{x}</b><br>Value: %{y:.2f}<extra></extra>'
)

# Add rangeslider
fig.update_xaxes(rangeslider_visible=True)

# Animations
animation_df = pd.DataFrame({'x': [1, 2], 'y': [10, 11], 'year': [2025, 2026]})
fig = px.scatter(animation_df, x='x', y='y', animation_frame='year')

完全なインタラクティブ性ガイドについては reference/export-interactivity.md を参照してください。

4. エクスポートオプション

インタラクティブ HTML:

fig.write_html('chart.html')                       # Full standalone
fig.write_html('chart.html', include_plotlyjs='cdn')  # Smaller file

静的画像（kaleido が必要）:

uv pip install kaleido

fig.write_image('chart.png')   # PNG
fig.write_image('chart.pdf')   # PDF
fig.write_image('chart.svg')   # SVG

完全なエクスポートオプションについては reference/export-interactivity.md を参照してください。

一般的なワークフロー

科学データのビジュアライゼーション

import plotly.express as px

# Scatter plot with trendline
fig = px.scatter(df, x='temperature', y='yield', trendline='ols')

# Heatmap from matrix
fig = px.imshow(correlation_matrix, text_auto=True, color_continuous_scale='RdBu')

# 3D surface plot
import plotly.graph_objects as go
fig = go.Figure(data=[go.Surface(z=z_data, x=x_data, y=y_data)])

統計分析

# Distribution comparison
fig = px.histogram(df, x='values', color='group', marginal='box', nbins=30)

# Box plot with all points
fig = px.box(df, x='category', y='value', points='all')

# Violin plot
fig = px.violin(df, x='group', y='measurement', box=True)

時系列と金融

# Time series with rangeslider
fig = px.line(df, x='date', y='price')
fig.update_xaxes(rangeslider_visible=True)

# Candlestick chart
import plotly.graph_objects as go
fig = go.Figure(data=[go.Candlestick(
    x=df['date'],
    open=df['open'],
    high=df['high'],
    low=df['low'],
    close=df['close']
)])

複数プロットのダッシュボード

from plotly.subplots import make_subplots
import plotly.graph_objects as go

fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=('Scatter', 'Bar', 'Histogram', 'Box'),
    specs=[[{'type': 'scatter'}, {'type': 'bar'}],
           [{'type': 'histogram'}, {'type': 'box'}]]
)

fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]), row=1, col=1)
fig.add_trace(go.Bar(x=['A', 'B'], y=[1, 2]), row=1, col=2)
fig.add_trace(go.Histogram(x=data), row=2, col=1)
fig.add_trace(go.Box(y=data), row=2, col=2)

fig.update_layout(height=800, showlegend=False)

Dash との統合

インタラクティブな Web アプリケーションには、Dash（Plotly の Web アプリフレームワーク）を使用します:

uv pip install dash

import dash
from dash import dcc, html
import plotly.express as px

app = dash.Dash(__name__)

fig = px.scatter(df, x='x', y='y')

app.layout = html.Div([
    html.H1('Dashboard'),
    dcc.Graph(figure=fig)
])

app.run(debug=True)  # local development only; disable debug for deployment

参照ファイル

• plotly-express.md - 迅速なビジュアライゼーションのための高レベル API
• graph-objects.md - 細かい制御のための低レベル API
• chart-types.md - 例を含む 40 種類以上のチャートタイプの完全なカタログ
• layouts-styling.md - サブプロット、テンプレート、色、カスタマイズ
• export-interactivity.md - エクスポートオプションとインタラクティブ機能

その他のリソース

• 公式ドキュメント: https://plotly.com/python/
• API リファレンス: https://plotly.com/python-api-reference/
• コミュニティフォーラム: https://community.plotly.com/

制限事項

• タスクが上記の説明にある範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。

上記に記載されている reference/*.md ガイドは上流の参照資料であり、ここには同梱されていません。依存する詳細については、公式ドキュメントを使用してください。エクスポートされた HTML には、プロットされたデータ（ホバーフィールドを含む）が含まれています。共有する前に内容を確認してください。CDN へのエクスポートにはネットワークアクセスが必要です。また、現在の Kaleido バージョンでは、利用可能な Chrome のインストールが必要になる場合があります。Dash 3 migration。