Plotly Interactive Viz

何时使用

需要交互式图表时用本技能：图表要支持悬停提示、缩放/平移、图例切换、框选，或要嵌入网页/仪表盘/演示。典型场景——探索性分析 notebook、仪表盘、时间序列 rangeslider、3D 曲面、金融 K 线。

不该用的边界：

• 要无交互的出版级静态图（论文 figure、PDF 矢量）→ 用 matplotlib，不是 Plotly。
• 要全栈交互 Web 应用（回调、表单、多页）→ Plotly 只负责画图，应用层用 Dash。
• 仅需 D3 级别完全自定义的浏览器原生可视化 → 见 d3js-data-viz。

步骤 / 指令

1. 安装：uv pip install plotly；需导出 PNG/PDF/SVG 再装 uv pip install kaleido。
2. 选 API（关键决策）：
   • Plotly Express（px）——高层、1~5 行、直接吃 pandas DataFrame、自动配色与图例。标准图（scatter/line/bar/histogram…）首选。
   • Graph Objects（go）——低层、精细控制。用于 px 没有的图（3D mesh、isosurface、复杂金融图）、从零搭多 trace、自定义形状/注解。
   • 二者可混用：px 返回的就是 go.Figure，可继续 fig.update_layout() / fig.add_hline()。
3. 画图 → 调样式（template、update_traces、update_xaxes）→ 输出（fig.show() / write_html / write_image）。
4. 多图仪表盘用 make_subplots，并在 specs 里声明各格 type。

示例

最小起步（Plotly Express）：

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()

常用工作流：

# 带趋势线散点 / 相关性热力图
fig = px.scatter(df, x='temperature', y='yield', trendline='ols')
fig = px.imshow(corr, text_auto=True, color_continuous_scale='RdBu')

# 分布对比 / 箱线（全点）/ 小提琴
fig = px.histogram(df, x='values', color='group', marginal='box', nbins=30)
fig = px.box(df, x='category', y='value', points='all')
fig = px.violin(df, x='group', y='measurement', box=True)

# 时间序列 + rangeslider；动画
fig = px.line(df, x='date', y='price'); fig.update_xaxes(rangeslider_visible=True)
fig = px.scatter(df, x='x', y='y', animation_frame='year')

Graph Objects（px 覆盖不到的图）：

import plotly.graph_objects as go
# 3D 曲面
fig = go.Figure(data=[go.Surface(z=z_data, x=x_data, y=y_data)])
# K 线
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
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.update_layout(height=800, showlegend=False)

交互定制与导出：

fig.update_traces(hovertemplate='<b>%{x}</b><br>Value: %{y:.2f}<extra></extra>')
fig.write_html('chart.html')                          # 独立 HTML
fig.write_html('chart.html', include_plotlyjs='cdn')  # 体积更小
fig.write_image('chart.png')   # 需 kaleido；支持 .pdf / .svg

模板（统一样式）：template='plotly_dark'（内置 plotly_white plotly_dark ggplot2 seaborn simple_white）。

嵌入 Web 应用（Dash）：

import dash
from dash import dcc, html
app = dash.Dash(__name__)
app.layout = html.Div([html.H1('Dashboard'), dcc.Graph(figure=px.scatter(df, x='x', y='y'))])
app.run_server(debug=True)

注意事项

• 静态导出依赖 kaleido：write_image 缺它会报错，先 uv pip install kaleido。
• HTML 体积：include_plotlyjs='cdn' 显著减小文件，但离线打开需联网拉 plotly.js；要完全离线就用默认（内联，约 3MB+）。
• hovertemplate 必须以 <extra></extra> 结尾才能隐藏右侧次要标签框。
• make_subplots 的 specs type 要和 trace 类型对应，否则 trace 加不进对应格子。
• 大数据量散点考虑 px.scatter(render_mode='webgl') 或 go.Scattergl，避免 SVG 渲染卡顿。
• 仅当任务确属交互式可视化范围时用本技能；缺少数据列/成功判据时先澄清，输出仍需在目标环境实测验证。
• 官方文档 https://plotly.com/python/ ；API 参考 https://plotly.com/python-api-reference/ 。

互见

• related：d3js-data-viz —— 需要浏览器原生、完全自定义的可视化时改用 D3。
• related：guided-statistical-analysis —— 统计分析产出的结果用 Plotly 画分布/箱线/小提琴图。
• combines_with：csv-data-cleaner —— 先清洗成规整 DataFrame，再喂给 Plotly Express 画图。
• combines_with：kpi-dashboard-design —— 先定指标与版式，再用 make_subplots 落地交互式仪表盘。

采编自 sickn33/antigravity-awesome-skills（MIT），原作者 K-Dense Inc.，适配重写并精简。