alterlab-plotly

Plotly

40 種類以上のチャートタイプで、インタラクティブかつ出版品質の可視化を作成する Python グラフ作成ライブラリです。例は plotly >= 6 を対象としており、plotly 7.1（plotly.js 4）で動作します。古いコードをアップグレードする場合は、以下の「Plotly 7 の変更点」を参照してください。

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

チャートをインタラクティブに操作したり共有したりする必要がある場合に、このスキルを使用します。

• ホバーツールチップ、ズーム／パン、凡例の切り替え、レンジスライダー、ドロップダウン、アニメーションフレーム
• 単独の HTML や Web に埋め込む図、Dash ダッシュボード
• 回転可能な 3D プロット（surface、scatter3d、mesh、volume）
• 読者が個々のポイントを確認する必要がある探索的分析

対象外

シナリオ	代わりに使用
インタラクティブ機能のない、印刷向けの静的な図	alterlab-matplotlib
ジャーナル形式の複数パネル図（カラム幅、Okabe-Ito パレット、有意差を示す星印）	alterlab-scientific-viz
DataFrame から手早く作成する静的な統計プロット（ヒートマップ、ペアプロット、分布）	alterlab-seaborn
フローチャート、経路図、アーキテクチャ図	alterlab-scientific-schematics / alterlab-mermaid

クイックスタート

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 行）で済ませたい

詳しいガイドは references/plotly-express.md を参照してください。

Graph Objects（go）を使用する

細かな制御やカスタムの可視化に適しています。

• Plotly Express にないチャートタイプ（3D メッシュ、等値面、複雑な金融チャート）
• 複雑な複数トレースの図を一から作成する
• 個々のコンポーネントを正確に制御する必要がある
• カスタムの図形や注釈を使った特殊な可視化を作成する

詳しいガイドは references/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 種類以上のチャートタイプをサポートしています。

基本的なチャート： scatter、line、bar、pie、area、bubble

統計チャート： histogram、box plot、violin、distribution、error bars

科学分野のチャート： heatmap、contour、ternary、画像表示

金融チャート： candlestick、OHLC、waterfall、funnel、時系列

マップ： 散布図マップ、コロプレス、密度マップ（地理情報対応、MapLibre ベース。*_mapbox 関数とトレースは plotly 7 で削除されました）

3D チャート： scatter3d、surface、mesh、cone、volume

特殊なチャート： sunburst、treemap、sankey、平行座標、ゲージ

すべてのチャートタイプの詳細な例と使い方は、references/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

カスタマイズ： 外観のあらゆる要素を制御できます。

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

レイアウトとスタイルの設定項目について詳しくは、references/layouts-styling.md を参照してください。

3. インタラクティブ機能

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

• データをカスタマイズできるホバーツールチップ
• パンとズーム
• 凡例の切り替え
• ボックス選択／投げ縄選択
• 時系列用のレンジスライダー
• ボタンとドロップダウン
• アニメーション

# 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
fig = px.scatter(df, x='x', y='y', animation_frame='year')

インタラクティブ機能の詳しいガイドは、references/export-interactivity.md を参照してください。

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

インタラクティブ HTML：

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

静的画像（kaleido >= 1 と Chrome が必要です）：

uv pip install kaleido
plotly_get_chrome    # one-time: installs a Chrome build if the machine has none

fig.write_image('chart.png', scale=3)   # PNG (700x500 default size -> 2100x1500 px)
fig.write_image('chart.pdf')            # PDF
fig.write_image('chart.svg')            # SVG

Chrome がインストールされていない場合、write_image は「Kaleido requires Google Chrome to be installed」というエラーを発生させます。エクスポートのデフォルト設定は plotly.io.defaults で指定します（例：pio.defaults.default_scale = 2）。以前の pio.kaleido.scope 設定は存在しません。

エクスポートオプションの詳細については、references/export-interactivity.md を参照してください。

よくあるワークフロー

科学データの可視化

import plotly.express as px

# Scatter plot with trendline (trendline='ols'/'lowess' requires statsmodels:
#   uv pip install statsmodels)
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 との統合

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

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)  # Dash >= 3 (current 4.x): run_server() was removed; use app.run()

Plotly 7 の変更点（2026 年 8 月）

Plotly 7.0 では plotly.js 4 に移行し、長らく非推奨だった API が削除されました。古いコードが動作しない場合：

• px.scatter_mapbox / density_mapbox / choropleth_mapbox / line_mapbox と go.*mapbox トレースは削除されました。px.scatter_map、px.density_map、px.choropleth_map、px.line_map を使用してください（MapLibre、map_style=、トークン不要）。
• 非推奨の figure-factory 関数が削除されました（create_annotated_heatmap、create_distplot、create_gantt、create_facet_grid、create_scatterplotmatrix、create_violin、create_candlestick、create_ohlc など）。代わりに Plotly Express を使用してください：px.imshow(z, text_auto=True)、px.histogram(..., marginal='rug')、px.timeline、px.scatter_matrix、px.violin、go.Candlestick / go.Ohlc。ff.create_dendrogram、create_quiver、create_streamline、create_table、create_trisurf、create_ternary_contour は引き続き使用できます。
• 静的エクスポートでサポートされるのは Kaleido >= 1 のみです（Orca はサポートされません）。また、write_image / to_image の engine= 引数は削除されました。
• 色文字列では、0～1 の小数チャンネルを指定した rgb() / rgba() と hsv() がサポートされなくなりました。rgba(255 0 0 / 0.5)、#ff0000aa、oklch() などの新しい形式が使用できるようになりました。
• ベクトル場向けに新しい go.Quiver トレースが追加されました。

リファレンスファイル

• 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/