使用 Plotly 与 Pandas 从 CSV 文件绘制图表:完整实战指南
使用 Plotly 与 Pandas 从 CSV 文件绘制图表:完整实战指南
CSV(Comma-Delimited Values,逗号分隔值)是存储结构化数据最流行的文本格式之一。本指南以 Plotly 官方文档 plot-data-from-csv.md 为核心脉络,系统讲解如何在 Python 中利用 pandas 读取 CSV 数据,并分别通过 Plotly Express 的 px.line 与底层 graph_objects 接口将其绘制成专业图表,同时覆盖 Dash 交互式应用场景。读完本文,你将掌握从"读取外部 CSV 数据源"到"完成图表定制与展示"的完整链路,并了解其背后的源码实现细节。
第一步:用 pandas 导入并预览 CSV 数据
无论是本地文件还是远程 URL,CSV 数据读取的统一入口都是 pandas 的 pd.read_csv()。Plotly 官方教程使用的示例数据是 2014 年苹果公司(Apple)的股票日线数据,直接通过 URL 读取:
import pandas as pd
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_apple_stock.csv')
df.head()
执行 df.head() 后,你会看到类似下面的表格结构,其中 AAPL_x 是日期列,AAPL_y 是当日收盘价(美元):
| AAPL_x | AAPL_y | |
|---|---|---|
| 0 | 2014-01-02 | 79.44 |
| 1 | 2014-01-03 | 77.64 |
| 2 | 2014-01-06 | 77.15 |
| ... | ... | ... |
实战提示:如果 CSV 文件在本地,把 URL 换成相对路径即可,例如 pd.read_csv('data/apple_stock.csv');如果数据量很大,还可以搭配 nrows、usecols 等参数先做抽样与列裁剪,避免一次性载入全量数据。
在动手绘图之前,务必确认两件事:一是列名(后续 x、y 参数要按列名引用);二是列的数据类型(日期列建议用 pd.to_datetime(df['AAPL_x']) 转为 datetime,这样 Plotly 才能在时间轴上正确排序与格式化刻度)。
方法一:使用 Plotly Express 一行绘制折线图
Plotly Express(plotly.express,常简写为 px)是 Plotly 的高层 API,专为"用最少代码完成探索性可视化"设计。直接从 DataFrame 绘图:
import pandas as pd
import plotly.express as px
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_apple_stock.csv')
fig = px.line(df, x='AAPL_x', y='AAPL_y', title='Apple Share Prices over time (2014)')
fig.show()
fig.show() 会根据当前运行环境自动选择渲染方式:在 Jupyter Notebook 中内联显示交互图表,在脚本环境中则打开浏览器页面,也可通过配置 renderers 切换到 iframe、svg 或静态图片等后端(详见 renderers.md)。
px.line 的核心参数
从 plotly/express/_chart_types.py 的源码签名可以看到,px.line 在 data_frame 基础上提供了丰富的映射参数:
x/y:指定作为横轴、纵轴的 DataFrame 列名(或 pandas Series / 数组),定位散点顶点位置;color:按某列取值对线条分组着色,例如color='year'可一次画出多年趋势;line_group:将数据行分组成多条独立折线(当color未指定分组时尤其有用);line_dash/symbol:按列值区分线型与标记符号;markers:设为True时在每个数据点处显示标记;log_x/log_y:坐标轴切换为对数刻度;range_x/range_y:显式限定坐标轴范围;facet_row/facet_col:按列值拆分为多行/多列子图;title/subtitle:图表主标题与副标题;template/width/height:控制主题外观与画布尺寸;labels:用字典重命名坐标轴与图例显示名,如labels={'AAPL_y': 'Close Price (USD)'}。
实现上,px.line 只是将全部参数转发给 plotly/express/_core.py 中的 make_figure(args=locals(), constructor=go.Scatter),由统一的底层管线完成列名解析、分组聚合与子图布局后,生成一个 go.Scatter 类型的 Figure 对象。
多序列与宽表数据
px.line 天然支持"宽表"(wide-form)数据:每一列是一个序列。例如仓库内置的股票数据集(6 家科技公司 2018/2019 年收盘价,见 plotly/data/init.py):
import plotly.express as px
from plotly.data import stocks
df = stocks() # 列: ['date', 'GOOG', 'AAPL', 'AMZN', 'FB', 'NFLX', 'MSFT']
fig = px.line(df, x='date', y=['GOOG', 'AAPL', 'AMZN', 'FB', 'NFLX', 'MSFT'])
fig.show()
传入 y 一个列名列表时,Plotly 会为每个公司绘制一条独立折线并自动生成图例。
方法二:使用 graph_objects 精细控制图表
plotly.graph_objects(常简写为 go)是 Plotly 的底层对象化 API,适合对图表结构进行细粒度定制。官方教程的等价实现如下:
import pandas as pd
import plotly.graph_objects as go
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_apple_stock.csv')
fig = go.Figure(go.Scatter(x=df['AAPL_x'], y=df['AAPL_y'],
name='Share Prices (in USD)'))
fig.update_layout(title=dict(text='Apple Share Prices over time (2014)'),
plot_bgcolor='rgb(230, 230,230)',
showlegend=True)
fig.show()
这段代码与 px.line 版本效果等价,但结构上更"显式":
go.Figure(...):创建空 Figure,传入的第一个参数即要添加的 trace(轨迹);go.Scatter(x=..., y=...):直接以 pandas Series 作为坐标数据(x、y接受数组、Series 或列表),name设置图例名称;fig.update_layout(...):在布局层统一设置——title支持字典形式(text字段),plot_bgcolor修改绘图区背景色,showlegend=True显式开启图例。
go.Scatter 由 plotly/graph_objs/_scatter.py 中的 Scatter 类实现,继承自统一的 _BaseTraceType,其属性通过校验器(validator)机制保证类型安全,错误属性名会在赋值时立即抛出异常而非静默忽略——这是 graph_objects 相比纯字典写法更可靠的关键原因。
更细的定制:模式与样式
go.Scatter 支持 mode 参数组合线、点与文本:
fig = go.Figure(go.Scatter(x=df['AAPL_x'], y=df['AAPL_y'],
mode='lines+markers',
line=dict(color='firebrick', width=2),
marker=dict(size=6, symbol='circle'),
name='Close Price'))
line 与 marker 均为嵌套对象,可继续指定颜色、宽度、符号、大小等属性;mode 可取 'lines'、'markers'、'lines+markers'、'text' 等组合。如果你希望同时用 px 和 go 混排(例如底层叠加自定义 annotation),完全可以把 px 生成的 Figure 直接传给后续的 fig.update_layout() 继续加工,两者产出的都是同一个 go.Figure 对象。
方法三:在 Dash 中构建基于 CSV 数据的分析应用
Dash 是 Plotly 官方推出的、用 Python 构建分析型 Web 应用的开源框架。官方文档强调它是"用 Plotly 图表在 Python 中构建分析应用的最佳方式"。
以本教程为例,一个最小可运行的 Dash 应用大致如下:
import pandas as pd
import plotly.express as px
import dash
from dash import dcc, html
app = dash.Dash(__name__)
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_apple_stock.csv')
fig = px.line(df, x='AAPL_x', y='AAPL_y', title='Apple Share Prices over time (2014)')
app.layout = html.Div(children=[
html.H1('Apple Stock Dashboard'),
dcc.Graph(id='price-chart', figure=fig),
])
if __name__ == '__main__':
app.run_server(debug=True)
运行方式:先安装依赖 pip install dash,将上述代码保存为 app.py,然后在终端执行 python app.py,浏览器访问 http://127.0.0.1:8050 即可看到交互式图表。Dash 的 dcc.Graph 组件接收 Figure 对象并渲染为可缩放、可悬停查看数据的交互图;更进一步,还可以利用 Dash 的 @app.callback 机制,让用户通过下拉菜单、日期选择器动态切换 CSV 中的不同股票或时间段,把静态图表升级为真正的数据产品。
进阶:仓库内置数据集与长表/宽表数据形态
当前仓库在 plotly/data/init.py 中提供了多组开箱即用的内置数据集(实际数据文件以 .csv.gz 形式存放在 plotly/package_data/datasets 目录),非常适合练习 CSV 绘图:
gapminder():各国人均 GDP、预期寿命与人口(长表,适合散点/气泡图);stocks():6 家科技公司收盘价(宽表,适合多序列折线);tips():餐厅小费数据(含分类列,适合箱线图/直方图);iris():鸢尾花测量数据(经典分类数据集);medals_wide()/medals_long():同一数据的宽表与长表两种形态,用于对比数据形态对绘图 API 的影响;carshare()、election()、wind()、experiment()等。
例如:
import plotly.express as px
from plotly.data import gapminder
df = gapminder()
df.head()
fig = px.scatter(df, x='gdpPercap', y='lifeExp',
size='pop', color='continent', log_x=True,
title='Gapminder: GDP per capita vs Life Expectancy')
fig.show()
宽表 vs 长表:宽表(wide)每列是一个变量(如 stocks 中每家公司一列),长表(long)每一行是一个观测(如 gapminder 中每个国家-年份一行)。px 系列 API 对两种形态都友好:宽表直接把多个列名列表传给 y,长表则用 color、facet_col 等按列值分组。理解这两种形态,是把任意 CSV 快速映射到正确图表的钥匙。
源码视角:data_frame 是如何被处理的
从 plotly/express/_core.py 的实现可以看到,px 系列函数接收 data_frame 后,会先判断其是否为 pandas-like DataFrame(包括 pandas、modin.pandas、cudf 等),再通过 narwhals 抽象层统一转换为内部 DataFrame 结构进行列名解析;同时,x、y 等参数既可以是列名字符串,也可以是 pandas Series 或任意类数组对象——这正是"传列名"与"直接传 Series"两种写法都能工作的原因。若传入的列名在 data_frame 中不存在,make_figure 会抛出明确的报错提示(见 plotly/express/_core.py),帮助开发者快速定位列名拼写或数据加载问题。
更多参考
- 本文源文档:plot-data-from-csv.md
- Plotly Python 入门与 API 概览:getting-started.md
px.line完整参数签名与文档字符串:plotly/express/_chart_types.py- 高层 API 底层实现(
make_figure、列解析):plotly/express/_core.py - 内置数据集接口:plotly/data/init.py 与数据文件目录 plotly/package_data/datasets
- 图表渲染方式配置:renderers.md
- 更多 CSV 相关示例:折线图 line-charts.md、散点图 line-and-scatter.md、时间序列 time-series.md
要点回顾:读取 CSV 用 pd.read_csv;快速成图优先选 px.line(df, x=..., y=...);需要精细定制时改用 go.Figure(go.Scatter(...)) 并配合 update_layout;构建交互应用则引入 Dash。三条路径共享同一套 Figure 数据模型,你可以根据场景自由组合,把任何一份 CSV 数据快速变成可交互的专业图表。