plotly

Plotly

用于创建交互式、出版级可视化的 Python 绘图库，支持 40 多种图表类型。

何时使用

• 你需要具有悬停、缩放、平移或网页嵌入功能的交互式图表。
• 你正在构建仪表板、探索性分析 Notebook 或能从丰富交互中获益的演示文稿。
• 你希望在同一个可视化任务中在 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 多种图表类型，分为以下类别：

基础图表： 散点图、折线图、柱状图、饼图、面积图、气泡图

统计图表： 直方图、箱线图、小提琴图、分布图、误差条

科学图表： 热力图、等高线图、三元图、图像显示

金融图表： K 线图、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. 交互性

内置交互功能：

• 具有可自定义数据的悬停提示
• 平移和缩放
• 图例切换
• 框选/套索选择
• 用于时间序列的范围滑块
• 按钮和下拉菜单
• 动画

# 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 迁移指南。