scipy.cluster.hierarchy.

dendrogram

scipy.cluster.hierarchy.dendrogram(Z, p=30, truncate_mode=None, color_threshold=None, get_leaves=True, orientation='top', labels=None, count_sort=False, distance_sort=False, show_leaf_counts=True, no_plot=False, no_labels=False, leaf_font_size=None, leaf_rotation=None, leaf_label_func=None, show_contracted=False, link_color_func=None, ax=None, above_threshold_color='C0')

将层次聚类绘制为树状图。

树状图通过在非单元素簇及其子簇之间绘制 U 型连接线，来展示每个簇的组成。U 型线的顶部表示簇合并。U 型线的两个支脚表示哪些簇被合并了。两个支脚的长度代表子簇之间的距离，这也是两个子簇中原始观测值之间的表型距离 (cophenetic distance)。

参数:

Zndarray

编码层次聚类的层级连接矩阵，用于渲染树状图。有关 Z 格式的更多信息，请参阅 linkage 函数。

pint, 可选

truncate_mode 的 p 参数。

truncate_modestr, 可选

当派生连接的原始观测矩阵很大时，树状图可能难以阅读。截断用于压缩树状图。有几种模式：

None

不执行截断（默认）。注：'none' 是 None 的别名，为了向后兼容而保留。

'lastp'

在连接中最后形成的 p 个非单元素簇是连接中仅有的非叶节点；它们对应于 Z 中的第 Z[n-p-2:end] 行。所有其他非单元素簇都被收缩到叶节点中。

'level'

显示的树状图层级不超过 p 层。一个“层级”包括与最终合并相隔 p 次合并的所有节点。

注：'mtica' 是 'level' 的别名，为了向后兼容而保留。

color_thresholddouble, 可选

简而言之，令 \(t\) 为 color_threshold。如果簇节点 \(k\) 是剪切阈值 \(t\) 下方的第一个节点，则将其下方的所有子连接着色为相同颜色。连接距离大于或等于该阈值的节点的所有连接都使用默认的 matplotlib 颜色 'C0' 着色。如果 \(t\) 小于或等于零，则所有节点都着色为 'C0'。如果 color_threshold 为 None 或 'default'，则遵循 MATLAB(TM) 行为，阈值设置为 0.7*max(Z[:,2])。

get_leavesbool, 可选

在结果字典中包含一个列表 R['leaves']=H。对于每个 \(i\)，H[i] == j，簇节点 j 出现在叶节点从左到右遍历的第 i 个位置，其中 \(j < 2n-1\) 且 \(i < n\)。

orientationstr, 可选

绘制树状图的方向，可以是以下任何字符串：

'top'

在顶部绘制根节点，并向下绘制子连接。（默认）。

'bottom'

在底部绘制根节点，并向上绘制子连接。

'left'

在左侧绘制根节点，并向右绘制子连接。

'right'

在右侧绘制根节点，并向左绘制子连接。

labelsndarray, 可选

默认情况下，labels 为 None，因此使用原始观测值的索引来标记叶节点。否则，这是一个长度为 \(n\) 的序列，其中 n == Z.shape[0] + 1。labels[i] 的值是放在第 \(i\) 个叶节点下的文本，仅当该叶节点对应于原始观测值而非非单元素簇时。

count_sortstr 或 bool, 可选

对于每个节点 n，n 的两个子连接绘制的顺序（视觉上从左到右）由该参数决定，该参数可以是以下任何值：

False

不执行任何操作。

'ascending' 或 True

首先绘制簇中原始对象数量最少的子节点。

'descending'

首先绘制簇中原始对象数量最多的子节点。

注意，distance_sort 和 count_sort 不能同时为 True。

distance_sortstr 或 bool, 可选

对于每个节点 n，n 的两个子连接绘制的顺序（视觉上从左到右）由该参数决定，该参数可以是以下任何值：

False

不执行任何操作。

'ascending' 或 True

首先绘制直接后代之间距离最小的子节点。

'descending'

首先绘制直接后代之间距离最大的子节点。

注意 distance_sort 和 count_sort 不能同时为 True。

show_leaf_countsbool, 可选

当为 True 时，代表 \(k>1\) 个原始观测值的叶节点会被标记上括号内包含的观测值数量。

no_plotbool, 可选

当为 True 时，不执行最终渲染。如果只需要为渲染计算的数据结构，或者 matplotlib 不可用，这会很有用。

no_labelsbool, 可选

当为 True 时，树状图渲染中的叶节点旁边不会出现任何标签。

leaf_rotationdouble, 可选

指定旋转叶标签的角度（以度为单位）。未指定时，旋转基于树状图中的节点数量（默认为 0）。

leaf_font_sizeint, 可选

指定叶标签的字体大小（以磅为单位）。未指定时，大小基于树状图中的节点数量。

leaf_label_funclambda 或函数, 可选

当 leaf_label_func 是一个可调用函数时，对于每个簇索引为 \(k < 2n-1\) 的叶子。该函数应返回一个包含叶子标签的字符串。

索引 \(k < n\) 对应原始观测值，而索引 \(k \geq n\) 对应非单元素簇。

例如，要用单元素的节点 ID 标记它们，并用非单元素的 ID、数量和不一致系数标记它们，只需执行以下操作：

# First define the leaf label function.
def llf(id):
    if id < n:
        return str(id)
    else:
        return '[%d %d %1.2f]' % (id, count, R[n-id,3])

# The text for the leaf nodes is going to be big so force
# a rotation of 90 degrees.
dendrogram(Z, leaf_label_func=llf, leaf_rotation=90)

# leaf_label_func can also be used together with ``truncate_mode``,
# in which case you will get your leaves labeled after truncation:
dendrogram(Z, leaf_label_func=llf, leaf_rotation=90,
           truncate_mode='level', p=2)

show_contractedbool, 可选

当为 True 时，收缩到叶节点中的非单元素节点的高度将作为十字标记沿连接该叶节点的线段绘制。这仅在执行截断时有用（参见 truncate_mode 参数）。

link_color_funccallable, 可选

如果给定，link_color_function 将针对其要绘制的每个 U 型线对应的非单元素 ID 进行调用。该函数应返回用于绘制连接线的颜色，编码为 matplotlib 颜色字符串代码。例如：

dendrogram(Z, link_color_func=lambda k: colors[k])

使用 colors[k] 为每个未截断的非单元素节点 k 下方的直接连接着色。

axmatplotlib Axes 实例, 可选

如果为 None 且 no_plot 不为 True，则树状图将绘制在当前轴上。否则，如果 no_plot 不为 True，则树状图将绘制在给定的 Axes 实例上。如果树状图是更复杂图形的一部分，这将非常有用。

above_threshold_colorstr, 可选

此 matplotlib 颜色字符串设置高于 color_threshold 的连接线的颜色。默认值为 'C0'。

返回:

Rdict

为渲染树状图而计算的数据结构字典。它包含以下键：

'color_list'

颜色名称列表。第 k 个元素代表第 k 条连接线的颜色。

'icoord' 和 'dcoord'

它们各自都是列表的列表。令 icoord = [I1, I2, ..., Ip]，其中 Ik = [xk1, xk2, xk3, xk4]；且 dcoord = [D1, D2, ..., Dp]，其中 Dk = [yk1, yk2, yk3, yk4]，那么绘制的第 k 条连接线就是 (xk1, yk1) - (xk2, yk2) - (xk3, yk3) - (xk4, yk4)。

'ivl'

对应于叶节点的标签列表。

'leaves'

对于每个 i，H[i] == j，簇节点 j 出现在叶节点从左到右遍历的第 i 个位置，其中 \(j < 2n-1\) 且 \(i < n\)。如果 j 小于 n，则第 i 个叶节点对应于原始观测值。否则，它对应于一个非单元素簇。

'leaves_color_list'

颜色名称列表。第 k 个元素代表第 k 个叶子的颜色。

另请参阅

linkage, set_link_color_palette

附注

Z[:,2] 中的距离应该是单调的，否则树状图中会出现交叉。

数组 API 标准支持

dendrogram 除了支持 NumPy 之外，还对兼容 Python Array API 标准的后端提供实验性支持。请考虑通过设置环境变量 SCIPY_ARRAY_API=1 并提供 CuPy、PyTorch、JAX 或 Dask 数组作为数组参数来测试这些功能。支持以下后端与设备（或其他能力）的组合。

库	CPU	GPU
NumPy	✅	不适用
CuPy	不适用	⛔
PyTorch	✅	⛔
JAX	⚠️ 无 JIT	⛔
Dask	⚠️ 计算图	不适用

有关更多信息，请参阅 对数组 API 标准的支持。

示例

在浏览器中试用！

>>> import numpy as np
>>> from scipy.cluster import hierarchy
>>> import matplotlib.pyplot as plt

一个非常基础的示例

>>> ytdist = np.array([662., 877., 255., 412., 996., 295., 468., 268.,
...                    400., 754., 564., 138., 219., 869., 669.])
>>> Z = hierarchy.linkage(ytdist, 'single')
>>> plt.figure()
>>> dn = hierarchy.dendrogram(Z)

现在，在给定的坐标轴中绘制，改进配色方案并同时使用垂直和水平方向

>>> hierarchy.set_link_color_palette(['m', 'c', 'y', 'k'])
>>> fig, axes = plt.subplots(1, 2, figsize=(8, 3))
>>> dn1 = hierarchy.dendrogram(Z, ax=axes[0], above_threshold_color='y',
...                            orientation='top')
>>> dn2 = hierarchy.dendrogram(Z, ax=axes[1],
...                            above_threshold_color='#bcbddc',
...                            orientation='right')
>>> hierarchy.set_link_color_palette(None)  # reset to default after use
>>> plt.show()

返回在新标签页中打开