Plotly.py 三维气泡图(3D Bubble Chart)完整实战指南:从 Plotly Express 到 graph_objects 的尺寸、颜色与坐标轴精调

原创2026-09-20 21:59:161,637 阅读
文章标签:数据可视化图表库数据分析

Plotly.py 三维气泡图(3D Bubble Chart)完整实战指南:从 Plotly Express 到 graph_objects 的尺寸、颜色与坐标轴精调

导读:三维气泡图(3D Bubble Chart)是 Plotly.py 在三维散点图(Scatter3d)基础上,用气泡大小编码第三个数值维度的可视化形态。本文以官方指南 doc/python/3d-bubble-charts.md 为骨架,结合 plotly.express.scatter_3d 与 plotly.graph_objects.Scatter3d 两套 API 的源码实现,完整讲解气泡尺寸映射(sizemode / sizeref / sizemin)、颜色与色条(colorbar / colorscale)、三维场景(scene)坐标轴配置等核心技术点。读完后你将能够用一行 Express 代码快速出图,也能用 graph_objects 对气泡图进行像素级精调,并理解气泡面积与直径换算的底层规则。

一、两种建图路径:Pick Your API

在 Plotly.py 中构建 3D 气泡图有两条主流路径,它们在官方文档中并列出现,适用于不同场景:

路径 对应接口 适用场景 文件位置
高层封装(Plotly Express) px.scatter_3d(...) 快速从 DataFrame 出图,自动处理尺寸、颜色映射 plotly/express/_chart_types.py
底层对象(graph_objects) go.Scatter3d(...) 精细控制 trace 与 marker 的每一个属性 plotly/graph_objs/_scatter3d.py

从源码看,px.scatter_3d 本质上是 make_figure(args=locals(), constructor=go.Scatter3d) 的薄封装(见 plotly/express/_chart_types.py#L753-L800),最终产出的仍然是一个以 go.Scatter3d 为 trace 类型的 go.Figure。因此理解 go.Scatter3d 的属性体系(x / y / z / marker / mode 等,见 plotly/graph_objs/_scatter3d.py#L8-L57 中的 _valid_props),是掌握整个 3D 气泡图能力边界的基础。

二、用 Plotly Express 一行代码生成 3D 气泡图

官方文档的第一个示例使用内置的 gapminder 数据集,将「年份、大洲、人口」映射到三维坐标,用 gdpPercap 控制气泡大小、lifeExp 控制颜色:

import plotly.express as px
import numpy as np

df = px.data.gapminder()
fig = px.scatter_3d(
    df,
    x='year',          # X 轴:年份
    y='continent',     # Y 轴:大洲(类别型)
    z='pop',           # Z 轴:人口
    size='gdpPercap',  # 气泡大小 ← 人均 GDP
    color='lifeExp',   # 气泡颜色 ← 预期寿命
    hover_data=['country'],  # 悬停额外显示国家
)
fig.update_layout(scene_zaxis_type="log")  # Z 轴对数刻度
fig.show()

px.scatter_3d 的完整签名(plotly/express/_chart_types.py#L753-L800)还支持以下常用参数:

  • 坐标与分组:x / y / z、color、symbol、size、text;
  • 悬停信息:hover_name、hover_data、custom_data;
  • 误差棒:error_x / error_y / error_z 及其 _minus 变体(3D 场景下同样支持三轴误差线);
  • 动画:animation_frame、animation_group(气泡可随时间帧演进);
  • 映射定制:category_orders、labels、size_max、color_discrete_sequence、color_continuous_scale、range_color、opacity;
  • 坐标轴:log_x / log_y / log_z、range_x / range_y / range_z;
  • 画布:title、subtitle、template、width、height。

2.1 Express 底层如何换算气泡尺寸

在 px.scatter_3d 传入 size 后,plotly/express/_core.py#L2235-L2240 中的 infer_config 会先计算全局缩放因子:

sizeref = df.get_column(args["size"]).max() / args["size_max"] ** 2

其中 size_max 的默认值为 20(见 plotly/express/_core.py#L89)。随后在 plotly/express/_core.py#L347-L354 中,size 参数被写进 marker 的三个属性:

trace_patch["marker"]["size"] = trace_data.get_column(attr_value)
trace_patch["marker"]["sizemode"] = "area"   # Express 默认按面积
trace_patch["marker"]["sizeref"] = sizeref

也就是说,Express 默认采用 sizemode='area'(面积模式),使气泡的显示面积与数据值成正比——这是气泡图避免「直径线性放大导致面积夸张」的行业惯例。手动使用 go.Scatter3d 时则需自己设置这些属性。

三、用 graph_objects 手写三维气泡图:三个完整示例

3.1 示例一:简单气泡图(Simple Bubble Chart)

官方文档用 gapminderDataFiveYear.csv 数据(取第 750~1500 行)展示了最完整的 go.Scatter3d 写法:

import plotly.graph_objects as go
import pandas as pd

# 获取数据:本示例只用其中一部分(即第 750-1500 行)
df = pd.read_csv(
    'https://raw.githubusercontent.com/plotly/datasets/master/gapminderDataFiveYear.csv'
)

start, end = 750, 1500

fig = go.Figure(data=go.Scatter3d(
    x=df['year'][start:end],
    y=df['continent'][start:end],
    z=df['pop'][start:end],
    text=df['country'][start:end],   # 气泡上的文本标签(国家名)
    mode='markers',                  # 仅绘制标记点
    marker=dict(
        sizemode='diameter',         # 直径模式
        sizeref=750,                 # 缩放因子,控制气泡整体大小
        size=df['gdpPercap'][start:end],  # 大小数据 ← 人均 GDP
        color=df['lifeExp'][start:end],   # 颜色数据 ← 预期寿命
        colorscale='Viridis',             # 内置配色:Viridis
        colorbar_title='Life<br>Expectancy',  # 色条标题(<br> 换行)
        line_color='rgb(140, 140, 170)'   # 气泡描边颜色
    )
))

fig.update_layout(
    height=800,
    width=800,
    title=dict(text='Examining Population and Life Expectancy Over Time')
)

fig.show()

3.2 示例二:按变量缩放气泡(Bubble Chart Sized by a Variable)

第二个示例以太阳系行星为数据,将「距太阳距离、密度、重力」映射到三维坐标,用行星直径控制气泡大小,并为场景设置深色背景与白色轴标题:

import plotly.graph_objects as go

planets = ['Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', 'Pluto']
planet_colors = ['rgb(135, 135, 125)', 'rgb(210, 50, 0)', 'rgb(50, 90, 255)',
                 'rgb(178, 0, 0)', 'rgb(235, 235, 210)', 'rgb(235, 205, 130)',
                 'rgb(55, 255, 217)', 'rgb(38, 0, 171)', 'rgb(255, 255, 255)']
distance_from_sun = [57.9, 108.2, 149.6, 227.9, 778.6, 1433.5, 2872.5, 4495.1, 5906.4]
density = [5427, 5243, 5514, 3933, 1326, 687, 1271, 1638, 2095]
gravity = [3.7, 8.9, 9.8, 3.7, 23.1, 9.0, 8.7, 11.0, 0.7]
planet_diameter = [4879, 12104, 12756, 6792, 142984, 120536, 51118, 49528, 2370]

# 创建 trace,气泡大小由行星直径决定
fig = go.Figure(data=go.Scatter3d(
    x=distance_from_sun,
    y=density,
    z=gravity,
    text=planets,
    mode='markers',
    marker=dict(
        sizemode='diameter',
        sizeref=750,           # 关于 sizeref 的说明见下节
        size=planet_diameter,
        color=planet_colors,   # 直接传入颜色数组(类别型)
    )
))

fig.update_layout(
    width=800,
    height=800,
    title=dict(text="Planets!"),
    scene=dict(
        xaxis=dict(title=dict(text="Distance from Sun", font=dict(color="white"))),
        yaxis=dict(title=dict(text="Density", font=dict(color="white"))),
        zaxis=dict(title=dict(text="Gravity", font=dict(color="white"))),
        bgcolor="rgb(20, 24, 54)"   # 场景背景色
    )
)

fig.show()

3.3 示例三:自定义色条(Edit the Colorbar)

第三个示例与第二个结构相同,区别在于把 color 换成连续温度数据,并自定义了色条标题与三段式 colorscale:

import plotly.graph_objects as go

planets = ['Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', 'Pluto']
temperatures = [167, 464, 15, -20, -65, -110, -140, -195, -200, -225]
distance_from_sun = [57.9, 108.2, 149.6, 227.9, 778.6, 1433.5, 2872.5, 4495.1, 5906.4]
density = [5427, 5243, 5514, 3933, 1326, 687, 1271, 1638, 2095]
gravity = [3.7, 8.9, 9.8, 3.7, 23.1, 9.0, 8.7, 11.0, 0.7]
planet_diameter = [4879, 12104, 12756, 6792, 142984, 120536, 51118, 49528, 2370]

# 创建 trace,气泡大小由行星直径决定
fig = go.Figure(go.Scatter3d(
    x=distance_from_sun,
    y=density,
    z=gravity,
    text=planets,
    mode='markers',
    marker=dict(
        sizemode='diameter',
        sizeref=750,           # 关于 sizeref 的说明见下节
        size=planet_diameter,
        color=temperatures,    # 连续数值 → 颜色映射
        colorbar_title='Mean<br>Temperature',  # 色条标题,<br> 表示换行
        colorscale=[[0, 'rgb(5, 10, 172)'], [.3, 'rgb(255, 255, 255)'], [1, 'rgb(178, 10, 28)']]
        # 自定义三段色阶:深蓝 → 白 → 深红
    )
))

fig.update_layout(
    width=800,
    height=800,
    title=dict(text="Planets!"),
    scene=dict(
        xaxis=dict(title=dict(text="Distance from Sun", font=dict(color="white"))),
        yaxis=dict(title=dict(text="Density", font=dict(color="white"))),
        zaxis=dict(title=dict(text="Gravity", font=dict(color="white"))),
        bgcolor="rgb(20, 24, 54)"
    )
)

fig.show()

四、气泡尺寸三件套:sizemode / sizeref / sizemin

go.Scatter3d 的 marker 对象位于 plotly/graph_objs/scatter3d/_marker.py,其尺寸相关属性集中在 _valid_props 中的 sizemin / sizemode / sizeref(见 plotly/graph_objs/scatter3d/_marker.py#L26-L28)。三者只有在 marker.size 为数值数组时才生效。

4.1 sizemode:直径模式还是面积模式

根据 plotly/graph_objs/scatter3d/_marker.py#L394-L409 的源码 docstring:

  • 'diameter':size 数据值直接映射为标记点的直径(像素);
  • 'area':size 数据值映射为标记点的面积,直径按平方根换算。

官方文档两个手写示例均使用 sizemode='diameter'。注意 Express 与手写示例的默认差异:px.scatter_3d 自动写入 sizemode='area'(见 plotly/express/_core.py#L352),而手动构造 go.Scatter3d 时该属性默认不设置,需要显式指定,否则气泡尺寸渲染可能不符合预期。

4.2 sizeref:全局缩放因子

sizeref 是尺寸映射的核心调参旋钮,源码 docstring 定义(plotly/graph_objs/scatter3d/_marker.py#L415-L433):

  • 作用:决定 size 数值换算为屏幕像素时的整体缩放比例;
  • 取值:任意 int 或 float;
  • 用法:与 sizemode、sizemin 配合使用。

实战规律:sizeref 越大,气泡整体越小;sizeref 越小,气泡越大。官方示例中的 sizeref=750 是作者针对行星直径数据(数千量级)调出的经验值,你的数据量级不同时应相应调整。Express 则会在 plotly/express/_core.py#L2238-L2240 自动用 max(size) / size_max ** 2 计算出一个合适的 sizeref,无需手动干预。

4.3 sizemin:最小可见尺寸下限

sizemin 的源码定义 显示它是一个取值区间为 [0, inf] 的数字:当数据值很小导致气泡被缩放过小时,用 sizemin 可强制保证标记点的最小像素尺寸,避免小值气泡“消失”在场景中,非常适合数值跨度大的数据。

五、颜色映射与色条定制

3D 气泡图的 color 属性支持两类输入,渲染行为不同:

  1. 离散/类别数据(如示例二的行星颜色数组):直接逐点指定颜色,Plotly 会按 color_discrete_sequence 或传入的颜色数组逐个分配;
  2. 连续数值数据(如示例三的温度数组):触发 colorscale 映射,并自动显示 colorbar。

示例三展示了完整的连续色定制三要素:

marker=dict(
    color=temperatures,                          # 连续数据源
    colorscale=[[0, 'rgb(5, 10, 172)'],          # 自定义色阶:0 → 深蓝
                [.3, 'rgb(255, 255, 255)'],      #       0.3 → 白
                [1, 'rgb(178, 10, 28)']],        #       1.0 → 深红
    colorbar_title='Mean<br>Temperature',        # 色条标题(<br> 换行)
)
  • colorscale 接受 [[位置0~1, 颜色], ...] 的列表,颜色可用 rgb(...) 字符串;
  • colorbar_title 支持 HTML 换行标签 <br>(如 'Life<br>Expectancy');
  • 也可以直接使用内置配色名(如示例一的 colorscale='Viridis'),Plotly 内置了 Viridis、Plasma、Cividis 等十余种连续色阶,并可通过 color_continuous_scale 参数在 Express 中指定。

六、场景(scene)坐标轴与背景精调

go.Scatter3d 的三维坐标轴统一挂在 layout.scene 下(这也是 Scatter3d 的 _valid_props 中包含 scene 字段的原因,见 plotly/graph_objs/_scatter3d.py#L35)。官方示例展示了三种最常用的场景定制:

fig.update_layout(
    scene=dict(
        xaxis=dict(title=dict(text="Distance from Sun", font=dict(color="white"))),
        yaxis=dict(title=dict(text="Density", font=dict(color="white"))),
        zaxis=dict(title=dict(text="Gravity", font=dict(color="white"))),
        bgcolor="rgb(20, 24, 54)"   # 场景背景色(深色主题)
    )
)
  • 轴标题与字体:xaxis/yaxis/zaxis 下的 title.text 与 title.font.color,示例中为深色背景配白色标题;
  • 背景色:scene.bgcolor 接受 rgb(...) 字符串;
  • 对数刻度:Express 版示例通过 fig.update_layout(scene_zaxis_type="log") 将 Z 轴(人口)切换为对数刻度,以压制数量级差异(人口从百万到十亿,线性轴会压扁小值气泡);graph_objects 写法等价于 scene.zaxis.type='log'。

七、从官方示例到生产实践:调参速查

需求 Express 写法 graph_objects 写法
气泡按变量缩放 px.scatter_3d(df, ..., size='col') marker=dict(size=arr, sizemode='diameter', sizeref=...)
控制气泡整体大小 size_max=30(默认 20,越大气泡越大) 调小 sizeref
颜色映射连续变量 color='col' + color_continuous_scale='Viridis' marker=dict(color=arr, colorscale='Viridis')
颜色映射类别变量 color='col' + color_discrete_sequence=[...] marker=dict(color=['rgb(...)', ...])
自定义色条标题 labels={'col': 'Title'} 或 update 色条 marker=dict(colorbar_title='Title<br>Sub')
悬停显示额外字段 hover_data=['country'] 默认展示 text + x/y/z,可用 hovertemplate 定制
Z 轴对数刻度 fig.update_layout(scene_zaxis_type='log') scene=dict(zaxis=dict(type='log'))
深色场景 template='plotly_dark' scene=dict(bgcolor='rgb(20, 24, 54)')
限制最小气泡 —(Express 无直接参数) marker=dict(sizemin=...)

八、参考与深入阅读

官方文档在结尾推荐了两份权威参考,对应本项目中的自动生成代码:

  • go.Scatter3d 全部属性:对应源码 plotly/graph_objs/_scatter3d.py(_valid_props 列出全部可用属性,包括 line、projection、surfaceaxis、error_x/y/z、hovertemplate 等本指南未展开的进阶能力);
  • marker.sizeref 及其配套属性:对应源码 plotly/graph_objs/scatter3d/_marker.py(含 sizemode、sizemin、colorbar、colorscale、line 等完整定义)。

进阶建议:三维气泡图常与动画(animation_frame)、多场景子图(make_subplots + specs)结合,且可叠加 error_z 误差棒展示不确定性;当气泡数超过数万时,可评估 Scattergl(WebGL 渲染)以获得更流畅的交互体验——这些都是官方文档 doc/python/3d-scatter-plots.md 与 doc/python/animations.md 中延伸的主题。

登录后查看全文
plotly.py