使用 Plotly 在 Python 中绘制气泡地图(Bubble Maps):Plotly Express 与 go.Scattergeo 的完整实战指南
使用 Plotly 在 Python 中绘制气泡地图(Bubble Maps):Plotly Express 与 go.Scattergeo 的完整实战指南
本指南围绕 Plotly 官方文档的 Bubble Maps 主题展开,讲解如何在当前 plotly.py 项目中用 px.scatter_geo 一行代码快速生成气泡地图、通过 animation_frame 制作随时间演变的气泡动画,以及使用底层图对象 go.Scattergeo 精细化控制气泡大小(sizeref/sizemode)、配色、多子图叠加与底图(go.layout.Geo)外观。读完本文,你将掌握气泡地图从数据列映射、尺寸缩放到多图层配制的完整实战方案,并能直接运行文中的所有示例。
气泡地图的本质:地理散点图 + 尺寸编码
气泡地图(Bubble Map)是地理散点图(geographic scatter plot)的一种变体:每个数据行在地图上对应一个标记点,标记点的位置由经度/纬度(lon/lat)或地理位置标识(locations)决定,标记点的面积或直径则编码第三个数值维度(例如人口、病例数)。
在当前仓库中,气泡地图可以由以下 API 之一创建,它们最终都会落到地理 trace 上:
- Plotly Express 高层接口:
px.scatter_geo、px.line_geo、px.choropleth; - 图对象(graph objects) 底层接口:
go.Scattergeo、go.Choropleth。
无论使用哪种方式,只要图中包含上述 trace,就会在 figure 中携带一个 go.layout.Geo 对象,用于控制底图的外观(如投影方式、地图范围、海岸线、陆地颜色等),数据层则叠加在底图之上。从源码可以看到,px.scatter_geo 实际就是 go.Scattergeo 的薄封装:在 plotly/express/_chart_types.py 中,它把参数原样交给 make_figure,并以 constructor=go.Scattergeo 构造 trace:
return make_figure(
args=locals(),
constructor=go.Scattergeo,
trace_patch=dict(locationmode=locationmode),
)
因此,理解 px.scatter_geo 的每个参数,等价于理解 go.Scattergeo 对应的 trace 属性。
用 Plotly Express 快速生成气泡地图
Plotly Express 是 Plotly 的高层、易用接口,它能处理多种类型的数据输入(长格式、宽格式、NumPy 数组、Pandas DataFrame 等),并生成易于样式定制的 figure。使用 px.scatter_geo 时,DataFrame 的每一行被表示为一个标记点,其中传入 size 参数的列决定标记点的大小。
以下示例使用内置数据集 px.data.gapminder(),筛选 2007 年的数据,将每个国家的 pop(人口)映射为气泡大小:
import plotly.express as px
df = px.data.gapminder().query("year==2007")
fig = px.scatter_geo(df, locations="iso_alpha", color="continent",
hover_name="country", size="pop",
projection="natural earth")
fig.show()
这个例子里用到的参数及其作用如下:
| 参数 | 作用 | 对应 go.Scattergeo 属性 |
|---|---|---|
locations |
指定包含地理位置标识的列,例如 ISO 3166-1 alpha-3 国家代码(iso_alpha) |
locations |
locationmode |
说明 locations 值的匹配方式(如 ISO-3、USA-states、country names、geojson-id),未指定时由 Plotly 自动推断 |
locationmode |
color |
指定一列离散或连续数据,映射为标记颜色;离散数据生成图例分组 | marker.color + 图例分组 |
hover_name |
指定一列作为悬停提示的标题,例如国家名 | hovertext 相关 |
size |
指定一列数值数据,映射为标记点大小(气泡地图的核心) | marker.size |
projection |
指定地图投影方式,例如 natural earth、mercator、equirectangular 等 |
geo.projection.type |
animation_frame |
指定一列作为动画帧,生成随时间演变的动画(见下节) | 通过 frames 实现 |
从 scatter_geo 的完整函数签名(plotly/express/_chart_types.py)还可以看到更多可选参数:lat/lon(直接指定经纬度列)、geojson/featureidkey(用于 GeoJSON 区域匹配)、symbol(符号映射)、facet_row/facet_col(分面)、hover_data/custom_data(附加悬停数据)、size_max(控制缩放后气泡的最大像素直径)、scope(地图范围,如 world、usa、africa)、center(中心点)、fitbounds(自动缩放至数据边界)、basemap_visible(是否显示底图)以及 title/subtitle/template/width/height 等通用样式参数。
气泡地图动画:用 animation_frame 展示时间演变
把 animation_frame 指定为年份列(如 year),Plotly 会自动按该列取值切分数据帧,生成带播放条(play/pause 控件与滑杆)的动画气泡地图。仍以 gapminder 数据为例,不筛选年份,直接展示 1952–2007 年全球人口气泡随时间的演变:
import plotly.express as px
df = px.data.gapminder()
fig = px.scatter_geo(df, locations="iso_alpha", color="continent",
hover_name="country", size="pop",
animation_frame="year",
projection="natural earth")
fig.show()
动画机制说明:animation_frame="year" 会让 make_figure 按 year 的唯一值将数据拆分成若干帧(frames),每一帧对应一个年份的气泡布局;播放条可以前后拖动,animation_group 参数还可额外指定在帧之间保持"同一个对象"的列(例如国家名),使标记在帧切换时平滑过渡而非闪烁重排。
使用 go.Scattergeo 精细绘制气泡地图
当需要对每个 trace、每个标记的细节做底层控制时,可以直接使用图对象 go.Scattergeo。这一节展示两个经典案例。
美国城市人口气泡图:掌握 sizeref 缩放公式
go.Scattergeo 的标记大小由 marker.size 指定,但原始数值(如人口)往往过大或过小,直接用作像素直径并不合适,因此需要借助 sizeref 缩放。关于 sizeref 有三个关键要点:
-
推荐公式:为将气泡缩放到期望的最大直径,建议用以下公式计算
sizeref:sizeref = 2. * max(array of size values) / (desired maximum marker size ** 2) -
缩放方向:
sizeref大于 1 会减小渲染出的标记尺寸;sizeref小于 1 会增大标记尺寸。 -
配合 sizemode:建议同时把
sizemode设置为area,即让标记面积与数值成正比(而非直径),这在视觉上更符合"气泡大小代表数量"的直觉。sizemin可设定渲染的最小标记尺寸,避免小气泡过小不可见。
这三个属性在源码中均有对应定义(plotly/graph_objs/scattergeo/_marker.py):size 为数值或数值数组,sizemin/sizeref 为数值,sizemode 为枚举(可取值包括 diameter、area)。
下面的示例读取 2014 年美国城市人口数据,将城市按人口规模分为 5 个区间,每段区间使用一种颜色、单独一条 trace,并将人口除以 scale=5000 作为 size,配合 sizemode='area' 让气泡面积直观反映人口:
import plotly.graph_objects as go
import pandas as pd
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_us_cities.csv')
df.head()
df['text'] = df['name'] + '<br>Population ' + (df['pop']/1e6).astype(str)+' million'
limits = [(0,3),(3,11),(11,21),(21,50),(50,3000)]
colors = ["royalblue","crimson","lightseagreen","orange","lightgrey"]
cities = []
scale = 5000
fig = go.Figure()
for i in range(len(limits)):
lim = limits[i]
df_sub = df[lim[0]:lim[1]]
fig.add_trace(go.Scattergeo(
locationmode = 'USA-states',
lon = df_sub['lon'],
lat = df_sub['lat'],
text = df_sub['text'],
marker = dict(
size = df_sub['pop']/scale,
color = colors[i],
line_color='rgb(40,40,40)',
line_width=0.5,
sizemode = 'area'
),
name = '{0} - {1}'.format(lim[0],lim[1])))
fig.update_layout(
title_text = '2014 US city populations<br>(Click legend to toggle traces)',
showlegend = True,
geo = dict(
scope = 'usa',
landcolor = 'rgb(217, 217, 217)',
)
)
fig.show()
这个示例同时展示了几个实用技巧:
locationmode='USA-states'表示按美国州名匹配位置;此时坐标通过lon/lat直接给定(可参考locationmode属性文档,见 plotly/graph_objs/_scattergeo.py);text使用 HTML 片段(<br>换行)构建多行悬停文本;- 通过
limits分段与循环,把同一数据源拆成多条 trace,并用name生成图例分组,点击图例即可开关对应人口区间的气泡; update_layout中把geo.scope设为usa、landcolor设为浅灰色,只聚焦美国本土区域。
西非埃博拉病例地图:多坐标系叠加(geo + geo2)
第二个经典案例是 2014 年西非埃博拉疫情地图。它展示了更复杂的图对象能力:同一张图中配置两个 Geo 坐标系(geo 与 geo2),用大图展示按月推移的病例气泡,用左下角"插图(inset)"小图叠加 9 月份病例的 go.Choropleth 区域着色:
import plotly.graph_objects as go
import pandas as pd
df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_ebola.csv')
df.head()
colors = ['rgb(239,243,255)','rgb(189,215,231)','rgb(107,174,214)','rgb(33,113,181)']
months = {6:'June',7:'July',8:'Aug',9:'Sept'}
fig = go.Figure()
for i in range(6,10)[::-1]:
df_month = df.query('Month == %d' %i)
fig.add_trace(go.Scattergeo(
lon = df_month['Lon'],
lat = df_month['Lat'],
text = df_month['Value'],
name = months[i],
marker = dict(
size = df_month['Value']/50,
color = colors[i-6],
line_width = 0
)))
df_sept = df.query('Month == 9')
fig['data'][0].update(mode='markers+text', textposition='bottom center',
text=df_sept['Value'].map('{:.0f}'.format).astype(str)+' '+\
df_sept['Country'])
# Inset
fig.add_trace(go.Choropleth(
locationmode = 'country names',
locations = df_sept['Country'],
z = df_sept['Value'],
text = df_sept['Country'],
colorscale = [[0,'rgb(0, 0, 0)'],[1,'rgb(0, 0, 0)']],
autocolorscale = False,
showscale = False,
geo = 'geo2'
))
fig.add_trace(go.Scattergeo(
lon = [21.0936],
lat = [7.1881],
text = ['Africa'],
mode = 'text',
showlegend = False,
geo = 'geo2'
))
fig.update_layout(
title = go.layout.Title(
text = 'Ebola cases reported by month in West Africa 2014<br> \
Source: <a href="https://data.hdx.rwlabs.org/dataset/rowca-ebola-cases">\
HDX</a>'),
geo = go.layout.Geo(
resolution = 50,
scope = 'africa',
showframe = False,
showcoastlines = True,
landcolor = "rgb(229, 229, 229)",
countrycolor = "white" ,
coastlinecolor = "white",
projection_type = 'mercator',
lonaxis_range= [ -15.0, -5.0 ],
lataxis_range= [ 0.0, 12.0 ],
domain = dict(x = [ 0, 1 ], y = [ 0, 1 ])
),
geo2 = go.layout.Geo(
scope = 'africa',
showframe = False,
landcolor = "rgb(229, 229, 229)",
showcountries = False,
domain = dict(x = [ 0, 0.6 ], y = [ 0, 0.6 ]),
bgcolor = 'rgba(255, 255, 255, 0.0)',
),
legend_traceorder = 'reversed'
)
fig.show()
这个案例值得拆解的技术点:
- 按月循环追加 trace:
range(6,10)[::-1]按 6→9 月倒序循环([::-1]逆序保证绘制时图例顺序为 June、July、Aug、Sept 的视觉期望),每月数据用df.query('Month == %d' %i)过滤,病例数Value/50作为size,并按月份取不同色阶颜色; - 后处理首条 trace:
fig['data'][0].update(mode='markers+text', ...)把第一条(9 月)trace 改为"标记+文本"模式,在气泡下方居中标注"病例数 国家名"; - 双坐标系叠加:通过给 trace 传
geo='geo2',将go.Choropleth(9 月各国病例着色)与一个纯文本Scattergeo标签绑定到第二个地图坐标系geo2,再用domain把geo2缩放到左下角作为插图; go.layout.Geo底图配置:resolution=50指定地图边界分辨率(50 或 110)、scope='africa'限定非洲、projection_type='mercator'用墨卡托投影、lonaxis_range/lataxis_range裁剪经纬度显示范围、showframe=False隐藏边框、showcoastlines/countrycolor/coastlinecolor控制海岸线与国界样式;legend_traceorder='reversed'反转图例顺序,使月份在图例中从旧到新排列。
底图配置速查:go.layout.Geo 常用参数
气泡地图的"底图"由 go.layout.Geo 控制,既可以通过 px.scatter_geo 的 projection/scope/center/fitbounds/basemap_visible 等参数快捷设置,也可以通过 fig.update_layout(geo=dict(...)) 或 fig.update_geos(...) 精细调整。结合上文两个案例,常用配置参数汇总如下:
| 参数 | 作用 | 常用取值 |
|---|---|---|
scope |
地图显示范围 | world、usa、europe、asia、africa、north america、south america |
projection_type |
投影方式 | natural earth、mercator、equirectangular、orthographic、azimuthal equal area 等 |
resolution |
地图边界数据分辨率 | 50、110 |
lonaxis_range / lataxis_range |
裁剪经纬度显示范围 | 如 [-15.0, -5.0] / [0.0, 12.0] |
domain |
坐标系在画布中的布局区域 | dict(x=[0, 1], y=[0, 1]),可据此做多坐标系插图 |
landcolor / countrycolor / coastlinecolor |
陆地、国界、海岸线颜色 | 任意 CSS 颜色,如 rgb(217, 217, 217)、white |
showframe / showcoastlines / showcountries |
是否显示边框、海岸线、国界 | True / False |
bgcolor |
坐标系背景色,配合插图叠加时常用透明色 | 如 rgba(255, 255, 255, 0.0) |
更完整的底图配置说明可参考仓库中的 map-configuration.md;多坐标系与子图布局还可结合 map-subplots-and-small-multiples.md 阅读。
参考与延伸阅读
px.scatter_geo的完整参数与逐项说明,可查阅 plotly/express/_chart_types.py 中scatter_geo的函数签名及生成的 docstring;go.Scattergeo的全部 trace 属性(lon、lat、locations、locationmode、marker等),可查阅 plotly/graph_objs/_scattergeo.py;- 气泡尺寸控制相关的
size、sizemin、sizemode、sizeref属性定义,见 plotly/graph_objs/scattergeo/_marker.py; - 与本主题相邻的官方文档还包括:choropleth-maps.md(区域着色地图)、scatter-plots-on-maps.md(地理散点图)、plotly-express.md(高层接口总览)以及 map-configuration.md(底图配置详解)。
以上示例在支持 Jupyter Notebook 渲染器或浏览器环境的 Python 3 中均可直接运行;若在纯脚本环境下,可改用 fig.write_html("bubble_map.html") 导出交互式 HTML 后查看。