使用 Plotly 在 Python 中绘制交互式填充弦图(Filled Chord Diagram)完整实战指南
使用 Plotly 在 Python 中绘制交互式填充弦图(Filled Chord Diagram)完整实战指南
本篇技术指南围绕 plotly.py 仓库中 doc/unconverted/python/filled-chord-diagram.md 所展示的方法,完整讲解如何仅用 Plotly 的图形对象与 layout 形状机制,从零实现 Circos 风格的交互式填充弦图(Filled Chord Diagram)。文中以 5 位 Facebook 好友的评论数据为例,逐步拆解 ideogram(染色体段式圆弧)与 ribbon(带状连接)的几何构造、数据映射、Bézier 曲线控制点计算、SVG 路径生成以及 hover 交互信息配置。读完本文,你将掌握一套可复用的、不依赖任何外部图表库的弦图绘制算法,并理解其与 Plotly layout.shapes 底层渲染机制之间的对应关系。
弦图与填充弦图:用圆环表达关系数据
弦图(Chord Diagram)是一种用于可视化实体之间关系数据的圆形布局方法,最早通过 Circos(一款最初为展示基因组数据而设计的 Perl 软件包)得到广泛推广。它擅长回答两类问题:每个实体自身的总量(例如某成员发布的评论总数),以及实体两两之间的流量(例如两位朋友之间互相评论的数量)。
一个典型的弦图由两类图形对象构成:
- Ideogram:分布在圆环上的、颜色互不相同的圆弧段,每一段对应一个实体,其弧长正比于该实体的总量;
- Ribbon:连接两段 ideogram 的带状区域,由两条二次 Bézier 曲线和两段圆弧围成(可退化为一个点),其粗细表达两个实体之间流量的大小。
在 Python 社区,很长一段时间内都缺乏成熟的弦图绘制方案。本文展示的方法证明了:使用 Plotly 的 scatter 轨迹与 layout.shapes 中的 SVG path 形状,即可完全在 Python 中生成交互式填充弦图,并且所有数据仅来源于一个方阵(square matrix)——矩阵的行与列代表同一组实体。
第一步:准备数据——Facebook 好友评论矩阵
本示例考察一个由 5 位好友(Emma、Isabella、Ava、Olivia、Sophia)组成的 Facebook 社区。我们记录每位成员在其他好友主页墙上发布的评论数量,得到一个 5×5 的方阵:
import numpy as np
matrix = np.array([[16, 3, 28, 0, 18],
[18, 0, 12, 5, 29],
[ 9, 11, 17, 27, 0],
[19, 0, 31, 11, 12],
[23, 17, 10, 0, 34]], dtype=int)
其中 matrix[i][j] 表示成员 i 在成员 j 的主页上发布的评论数,对角线元素表示成员在自己主页上的评论数。矩阵必须为方阵,可通过如下校验函数强制约束:
def check_data(data_matrix):
L, M = data_matrix.shape
if L != M:
raise ValueError('Data array must have (n,n) shape')
return L
L = check_data(matrix)
在正式绘图前,可以用 Plotly 的 Figure Factory 表格工具把原始数据直观地展示出来。仓库中的 plotly/figure_factory/_table.py 提供了 create_table 函数,它本质上基于 annotated heatmap 构建(trace = dict(type="heatmap", z=table_matrix, ...)),并通过 annotation 逐格写入文本;设置 index=True 时会额外生成一列带表头颜色的索引列,index_title 可指定索引列标题。它通过 plotly/figure_factory/init.py 对外导出:
import plotly.figure_factory as ff
data = [['', 'Emma', 'Isabella', 'Ava', 'Olivia', 'Sophia', 'row-sum'],
['Emma', 16, 3, 28, 0, 18, 65],
['Isabella', 18, 0, 12, 5, 29, 64],
['Ava', 9, 11, 17, 27, 0, 64],
['Olivia', 19, 0, 31, 11, 12, 73],
['Sophia', 23, 17, 10, 0, 34, 84]]
table = ff.create_table(data, index=True)
table.show() # 现代 plotly.py 中直接调用 show() 即可渲染
我们的可视化目标是同时表达两个信息层次:每位成员发布的评论总数(对应 ideogram 的弧长)与成员两两之间的评论流向(对应 ribbon 的粗细)。
Ideogram 的几何构造:把行和映射到单位圆
数学基础
对矩阵每一行求和,得到每个成员的总评论数(即上面表格中的 row-sum 列)。设 total_comments 为整个社区的评论总数,理论上区间 [0, total_comments) 可线性映射到单位圆,即区间 [0, 2π)。
为了使图形更美观,实际操作中从角度 0 出发、沿逆时针方向,依次在单位圆上绘制两条平行的圆弧,弧长等于映射后的行和减去一个固定间隙 gap:
PI = np.pi
# 设置两个连续 ideogram 之间的间隙(占圆周的 0.5%)
gap = 2 * PI * 0.005
row_sum = [np.sum(matrix[k, :]) for k in range(L)]
ideogram_length = 2 * PI * np.asarray(row_sum) / sum(row_sum) - gap * np.ones(L)
角度标准化:moduloAB 与 test_2PI
单位圆是逆时针定向的。为了得到端角坐标满足 θ₀ < θ₁ 的圆弧,需要处理“圆弧跨越角度 0 点”的情形(例如 θ₀ = 2π − π/12、θ₁ = π/9)。函数 moduloAB 把任意实数映射到区间 [a, b)(b − a = 2π);取 a = −π、b = π 时,可将 [0, 2π) 映射到 [−π, π),此时 θ₀ 映射为 −π/12、θ₁ 映射为 π/9,自然满足 θ₀′ < θ₁′:
def moduloAB(x, a, b): # 将实数 x 映射到与单位圆等价的区间 [a, b),b-a=2*PI
if a >= b:
raise ValueError('Incorrect interval ends')
y = (x - a) % (b - a)
return y + b if y < 0 else y + a
def test_2PI(x):
return 0 <= x < 2 * PI
计算每个 ideogram 的端点坐标
def get_ideogram_ends(ideogram_len, gap):
ideo_ends = []
left = 0
for k in range(len(ideogram_len)):
right = left + ideogram_len[k]
ideo_ends.append([left, right])
left = right + gap
return ideo_ends
ideo_ends = get_ideogram_ends(ideogram_length, gap)
make_ideogram_arc 返回圆弧上均匀分布的采样点,以极坐标形式的复数表示(实部为 x 坐标、虚部为 y 坐标),这些点的实部与虚部将用于构造 ideogram 的 SVG 路径。参数 a 控制圆弧上的采样点密度——按弧长比例 a*length/π 计算点数,弧长不超过 π/4 时至少取 5 个点:
def make_ideogram_arc(R, phi, a=50):
# R 是圆半径
# phi 是一条圆弧两个端角坐标组成的列表
# a 是控制圆弧上采样点数量的参数
if not test_2PI(phi[0]) or not test_2PI(phi[1]):
phi = [moduloAB(t, 0, 2 * PI) for t in phi]
length = (phi[1] - phi[0]) % 2 * PI
nr = 5 if length <= PI / 4 else int(a * length / PI)
if phi[0] < phi[1]:
theta = np.linspace(phi[0], phi[1], nr)
else:
phi = [moduloAB(t, -PI, PI) for t in phi]
theta = np.linspace(phi[0], phi[1], nr)
return R * np.exp(1j * theta)
z = make_ideogram_arc(1.3, [11 * PI / 6, PI / 17])
print(z) # 原文档为 Python 2 语法 print z,此处改为 Python 3
这些复数点的实部和虚部将用来把 ideogram 定义为 Plotly shape(由 SVG path 围成的形状),这正是 plotly/graph_objs/_layout.py 中 layout.shapes 属性所承载的机制——它是一组 plotly.graph_objs.layout.Shape 实例(源码第 1625-1641 行的 shapes 属性定义证实了这一点)。
设置 ideogram 的标签与颜色
labels = ['Emma', 'Isabella', 'Ava', 'Olivia', 'Sophia']
# Brewer 配色,alpha 设为 0.75
ideo_colors = ['rgba(244, 109, 67, 0.75)',
'rgba(253, 174, 97, 0.75)',
'rgba(254, 224, 139, 0.75)',
'rgba(217, 239, 139, 0.75)',
'rgba(166, 217, 106, 0.75)']
Ribbon 的数据映射:把矩阵元素映射到 ideogram 弧段
ideogram 回答的是“每个成员发了多少评论”,而 ribbon 回答的是“评论从谁流向谁”。为此需要把矩阵数据映射到单位圆上:对每一行 k,映射
t ↦ t * ideogram_length[k] / row_sum[k]
把区间 [0, row_sum[k]] 一一对应到区间 [0, ideogram_length[k]],于是第 k 行的每个元素 matrix[k][j] 被映射为 matrix[k][j] * ideogram_length[k] / row_sum[k]。map_data 完成全部元素的映射:
def map_data(data_matrix, row_value, ideogram_length):
mapped = np.zeros(data_matrix.shape)
for j in range(L):
mapped[:, j] = ideogram_length * data_matrix[:, j] / row_value
return mapped
mapped_data = map_data(matrix, row_sum, ideogram_length)
对于每一对 (mapped_data[k][j], mapped_data[j][k])(k ≤ j),关联一条 ribbon:它是以第 k 个 ideogram 的一段子弧与第 j 个 ideogram 的一段子弧为对边、以两段二次 Bézier 曲线为侧边的“曲线填充矩形”(可退化)。
为了让图形更美观,Circos 文档建议将 mapped_data 的每一行按递增顺序排序,从而让 ribbon 在 ideogram 内边界上的排列更规整:
idx_sort = np.argsort(mapped_data, axis=1)
下面计算 ribbon 的端点。我们称 l = [l[0], l[1]]、r = [r[0], r[1]] 为 ribbon 两端对边弧的端角坐标列表。make_ribbon_ends 从每个 ideogram 的起点出发,按排序后的顺序逐段累加,得到 L×L 个端点元组:
def make_ribbon_ends(mapped_data, ideo_ends, idx_sort):
L = mapped_data.shape[0]
ribbon_boundary = np.zeros((L, L + 1))
for k in range(L):
start = ideo_ends[k][0]
ribbon_boundary[k][0] = start
for j in range(1, L + 1):
J = idx_sort[k][j - 1]
ribbon_boundary[k][j] = start + mapped_data[k][J]
start = ribbon_boundary[k][j]
return [[(ribbon_boundary[k][j], ribbon_boundary[k][j + 1]) for j in range(L)]
for k in range(L)]
ribbon_ends = make_ribbon_ends(mapped_data, ideo_ends, idx_sort)
print('ribbon ends starting from the ideogram[2]\n', ribbon_ends[2])
注意:ribbon_ends[k][j] 对应 mapped_data[k][idx_sort[k][j]],即其弧长等于 mapped_data[k][idx_sort[k][j]]——这是后续把 ribbon 与正确数据关联起来的关键。
Bézier 曲线控制点与 SVG 路径生成
ribbon 的两条侧边是二次 Bézier 曲线。control_pts 计算控制点 b₀、b₁、b₂ 的笛卡尔坐标:b₀ 与 b₂ 位于单位圆上(仅由角坐标决定),b₁ 的角坐标取 b₀、b₂ 角坐标的均值,而 radius 参数控制 b₁ 到圆心的距离:
def control_pts(angle, radius):
# angle 是控制点 b0, b1, b2 角坐标组成的 3 元素列表
# radius 是 b1 到原点 O(0,0) 的距离
if len(angle) != 3:
raise ValueError('angle must have len = 3')
b_cplx = np.array([np.exp(1j * angle[k]) for k in range(3)])
b_cplx[1] = radius * b_cplx[1]
return list(zip(b_cplx.real, b_cplx.imag))
def ctrl_rib_chords(l, r, radius):
# 返回构成 ribbon 两条对边(二次 Bezier 曲线)控制多边形的 2 元素列表
# l (r) 是 ribbon 起始(结束)弧端角坐标组成的列表
# radius 是两个控制多边形共用的参数
if len(l) != 2 or len(r) != 2:
raise ValueError('the arc ends must be elements in a list of len 2')
return [control_pts([l[j], (l[j] + r[j]) / 2, r[j]], radius) for j in range(2)]
make_q_bezier 把一条由 3 个控制点定义的二次 Bézier 曲线翻译成 Plotly 可识别的 SVG path 片段(M 为起点、Q 为二次贝塞尔曲线命令):
def make_q_bezier(b): # 根据控制点列表生成二次 Bezier 曲线的 Plotly SVG path
if len(b) != 3:
raise ValueError('control polygon must have 3 points')
A, B, C = b
return 'M ' + str(A[0]) + ',' + str(A[1]) + ' ' + 'Q ' + \
str(B[0]) + ', ' + str(B[1]) + ' ' + \
str(C[0]) + ', ' + str(C[1])
b = [(1, 4), (-0.5, 2.35), (3.745, 1.47)]
make_q_bezier(b)
make_ribbon_arc 生成 ribbon 圆弧边的 SVG path(以 L 直线命令逐段逼近圆弧),并校验角坐标必须落在 [0, 2π] 内:
def make_ribbon_arc(theta0, theta1):
if test_2PI(theta0) and test_2PI(theta1):
if theta0 < theta1:
theta0 = moduloAB(theta0, -PI, PI)
theta1 = moduloAB(theta1, -PI, PI)
if theta0 * theta1 > 0:
raise ValueError('incorrect angle coordinates for ribbon')
nr = int(40 * (theta0 - theta1) / PI)
if nr <= 2:
nr = 3
theta = np.linspace(theta0, theta1, nr)
pts = np.exp(1j * theta) # 圆弧上的点,极坐标复数形式
string_arc = ''
for k in range(len(theta)):
string_arc += 'L ' + str(pts.real[k]) + ', ' + str(pts.imag[k]) + ' '
return string_arc
else:
raise ValueError('the angle coordinates for an arc side of a ribbon must be in [0, 2*pi]')
make_ribbon_arc(np.pi / 3, np.pi / 6)
为 ribbon 配色
每条 ribbon 使用它所连接的两个 ideogram 之一的颜色。定义对称的 L×L 颜色结构 ribbon_color[k][j],表示连接第 k 个与第 j 个 ideogram 子弧的 ribbon 颜色:
ribbon_color = [L * [ideo_colors[k]] for k in range(L)]
随后按需覆盖个别位置的颜色(对称位置不必修改,因为绘制时只访问 k ≤ j 的元素):
ribbon_color[0][4] = ideo_colors[4]
ribbon_color[1][2] = ideo_colors[2]
ribbon_color[2][3] = ideo_colors[3]
ribbon_color[2][4] = ideo_colors[4]
组装 Plotly 图形:layout、ideogram 形状与 ribbon 形状
构造无坐标轴的圆形画布
弦图本质上是纯几何图形,不需要坐标轴。make_layout 隐藏轴线、网格与刻度,关闭图例,并把 shapes 初始化为空列表(后续追加 ribbon 与 ideogram 的形状字典):
import plotly.graph_objects as go
def make_layout(title, plot_size):
axis = dict(showline=False, # 隐藏轴线、网格、刻度标签与标题
zeroline=False,
showgrid=False,
showticklabels=False,
title='')
return go.Layout(title=title,
xaxis=dict(axis),
yaxis=dict(axis),
showlegend=False,
width=plot_size,
height=plot_size,
margin=dict(t=25, b=25, l=25, r=25),
hovermode='closest',
shapes=[] # 后续将 ribbon、ideogram 形状字典追加到此列表
)
layout = make_layout('Chord diagram', 400)
生成 ideogram 形状
make_ideo_shape 把前面算出的 SVG path 封装成 layout.shapes 中的一个形状字典:type='path'、layer='below' 表示置于底层、fillcolor 指定填充色、line 控制边界颜色与宽度:
def make_ideo_shape(path, line_color, fill_color):
# line_color 是形状边界颜色
# fill_color 是 ideogram 的填充颜色
return dict(
line=dict(color=line_color, width=0.45),
path=path,
type='path',
fillcolor=fill_color,
layer='below'
)
生成 ribbon 形状
弦图中有两类 ribbon:连接两个不同 ideogram 的普通 ribbon,以及从某 ideogram 回到自身的 ribbon(对应 mapped_data[k][k],表达“成员给自己主页评论”的流量):
def make_ribbon(l, r, line_color, fill_color, radius=0.2):
# l=[l[0], l[1]], r=[r[0], r[1]] 是 ribbon 两条对边弧
# line_color 是形状边界颜色,fill_color 是 ribbon 填充色
poligon = ctrl_rib_chords(l, r, radius)
b, c = poligon
return dict(
line=dict(color=line_color, width=0.5),
path=make_q_bezier(b) + make_ribbon_arc(r[0], r[1]) +
make_q_bezier(c[::-1]) + make_ribbon_arc(l[1], l[0]),
type='path',
fillcolor=fill_color,
layer='below'
)
def make_self_rel(l, line_color, fill_color, radius):
# radius 是 Bezier 控制点 b_1 的半径
b = control_pts([l[0], (l[0] + l[1]) / 2, l[1]], radius)
return dict(
line=dict(color=line_color, width=0.5),
path=make_q_bezier(b) + make_ribbon_arc(l[1], l[0]),
type='path',
fillcolor=fill_color,
layer='below'
)
def invPerm(perm):
# 返回排列 perm 的逆排列
inv = [0] * len(perm)
for i, s in enumerate(perm):
inv[s] = i
return inv
把 ribbon 关联到正确的数据,并添加 hover 交互
这是整个算法最微妙的一步。由 ribbon_ends 的定义可知,ribbon_ends[k][j] 对应 matrix[k][sigma[j]],其中 sigma 是使第 k 行在 mapped_data 中递增排序的索引排列。若 sigma_inv 是 sigma 的逆排列,那么 matrix[k][j] 对应 ribbon_ends[k][sigma_inv[j]]。
对角线自环 ribbon 的 Bézier 控制点 b₁ 需要单独调参(控制自环的曲率半径),文档给出了一组经验值:
radii_sribb = [0.4, 0.30, 0.35, 0.39, 0.12] # 这些值经过数次试验确定
主循环遍历 k ≤ j 的矩阵元素:跳过双向都为零的条目;对 j == k 绘制自环并添加“成员给自己评论”的 hover 文本;对 j != k 分别计算两个 ribbon 端点的中点在 0.9 半径处的坐标,用两个不可见的微小 marker(marker=dict(size=0.5))承载两端各自的 hover 文本,并在追加形状时反转 r 的端点顺序(r = (r[1], r[0]),否则 ribbon 会扭转):
ribbon_info = []
for k in range(L):
sigma = idx_sort[k]
sigma_inv = invPerm(sigma)
for j in range(k, L):
if matrix[k][j] == 0 and matrix[j][k] == 0:
continue
eta = idx_sort[j]
eta_inv = invPerm(eta)
l = ribbon_ends[k][sigma_inv[j]]
if j == k:
layout['shapes'].append(make_self_rel(l, 'rgb(175,175,175)',
ideo_colors[k], radius=radii_sribb[k]))
z = 0.9 * np.exp(1j * (l[0] + l[1]) / 2)
text = labels[k] + ' commented on ' + '{:d}'.format(matrix[k][k]) + \
' of ' + 'herself Fb posts'
ribbon_info.append(go.Scatter(x=[z.real],
y=[z.imag],
mode='markers',
marker=dict(size=0.5, color=ideo_colors[k]),
text=text,
hoverinfo='text'))
else:
r = ribbon_ends[j][eta_inv[k]]
zi = 0.9 * np.exp(1j * (l[0] + l[1]) / 2)
zf = 0.9 * np.exp(1j * (r[0] + r[1]) / 2)
texti = labels[k] + ' commented on ' + '{:d}'.format(matrix[k][j]) + \
' of ' + labels[j] + ' Fb posts'
textf = labels[j] + ' commented on ' + '{:d}'.format(matrix[j][k]) + \
' of ' + labels[k] + ' Fb posts'
ribbon_info.append(go.Scatter(x=[zi.real],
y=[zi.imag],
mode='markers',
marker=dict(size=0.5, color=ribbon_color[k][j]),
text=texti,
hoverinfo='text'))
ribbon_info.append(go.Scatter(x=[zf.real],
y=[zf.imag],
mode='markers',
marker=dict(size=0.5, color=ribbon_color[k][j]),
text=textf,
hoverinfo='text'))
r = (r[1], r[0]) # 重要!反转弧端点,否则会产生扭转的 ribbon
layout['shapes'].append(make_ribbon(l, r, 'rgb(175,175,175)', ribbon_color[k][j]))
生成 ideogram 轨迹与 SVG 路径
ideograms 列表保存每个 ideogram 的 scatter 轨迹(在圆上绘制 spline 样条线,hover 时显示成员名与评论总数)以及对应的 SVG path 形状。路径由两条同心圆弧(半径 1.1 与 1.0)围成闭环:
ideograms = []
for k in range(len(ideo_ends)):
z = make_ideogram_arc(1.1, ideo_ends[k])
zi = make_ideogram_arc(1.0, ideo_ends[k])
m = len(z)
n = len(zi)
ideograms.append(go.Scatter(x=z.real,
y=z.imag,
mode='lines',
line=dict(color=ideo_colors[k], shape='spline', width=0.25),
text=labels[k] + '<br>' + '{:d}'.format(row_sum[k]),
hoverinfo='text'))
path = 'M '
for s in range(m):
path += str(z.real[s]) + ', ' + str(z.imag[s]) + ' L '
Zi = np.array(zi.tolist()[::-1]) # 内圈反向,构成闭合环
for s in range(m):
path += str(Zi.real[s]) + ', ' + str(Zi.imag[s]) + ' L '
path += str(z.real[0]) + ' ,' + str(z.imag[0])
layout['shapes'].append(make_ideo_shape(path, 'rgb(150,150,150)', ideo_colors[k]))
组装并渲染
原文档使用 go.Data(ideograms + ribbon_info) 组装数据,但在当前 plotly.py 中 plotly.graph_objs.Data 已被标记为弃用(见 plotly/graph_objs/_deprecations.py 第 8-42 行的 Data 类定义),直接传入普通列表即可;渲染既可走离线模式(模块入口见 plotly/offline/offline.py),也可用 fig.show():
data = ideograms + ribbon_info
fig = go.Figure(data=data, layout=layout)
fig.show()
# 若需离线输出到 notebook,可配合:
# import plotly.offline as off
# off.init_notebook_mode(connected=True)
# off.iplot(fig, filename='chord-diagram-Fb')
把同一个算法套用到 8 位 Facebook 好友的评论矩阵上,即可得到更丰富的社区关系弦图——ideogram 展示每位成员的总发言量,ribbon 清晰呈现每对成员之间的双向评论流量,鼠标悬停时两端的文本分别显示“A 评论了 B 的 N 条帖子”与“B 评论了 A 的 M 条帖子”。
运行环境与 API 演进说明
- 原文档的 notebook 元数据(front-matter)标注的 kernel 为 Python 2,代码中包含
print z等 Python 2 语法;现代环境请使用 Python 3,本文所有代码已做相应兼容改写。 - 原文档中的
import plotly.plotly as py与py.iplot(...)属于 plotly.py 旧版联网账户 API,在当前仓库中已不再作为推荐入口;离线绘图入口位于 plotly/offline/offline.py,现代统一推荐fig.show()或off.iplot(fig)。 go.Data、graph_objs别名等旧接口均已在 plotly/graph_objs/_deprecations.py 中标记弃用并给出替换建议(用普通list或plotly.graph_objs.Scatter等具体轨迹类型替代),建议按本文改写后的写法使用。- 所有 ideogram 与 ribbon 形状最终都写入
layout.shapes,该属性在 plotly/graph_objs/_layout.py 中被定义为一组plotly.graph_objs.layout.Shape实例,支持path、fillcolor、line、layer等属性——这正是本文所有几何计算能够落地的渲染基础设施。
小结
本文完整复现了 doc/unconverted/python/filled-chord-diagram.md 提出的“纯 Plotly 绘制填充弦图”方案,核心链路为:方阵数据 → 行和映射为 ideogram 弧长 → 行内元素映射为 ribbon 弧长并排序 → 计算 ribbon 端点与 Bézier 控制点 → 生成 SVG path → 写入 layout.shapes 与 scatter 轨迹 → 渲染出带 hover 交互的交互式弦图。整套代码不依赖 d3.js 或其他第三方弦图库,全部基于 Plotly 自身能力实现,可直接复用到任意以方阵形式表达的双向关系数据(如迁移矩阵、流量矩阵、基因互作数据等),只需替换 matrix、labels 与 ideo_colors 即可快速生成你自己的填充弦图。