`scipy.cluster.hierarchy:to_tree`

source: /scipy/cluster/hierarchy.py :1395

Signature

def to_tree ( Z , rd = False )

Summary

Convert a linkage matrix into an easy-to-use tree object.

Extended Summary

The reference to the root ClusterNode object is returned (by default).

Each ClusterNode object has a left, right, dist, id, and count attribute. The left and right attributes point to ClusterNode objects that were combined to generate the cluster. If both are None then the ClusterNode object is a leaf node, its count must be 1, and its distance is meaningless but set to 0.

Note: This function is provided for the convenience of the library user. ClusterNodes are not used as input to any of the functions in this library.

Parameters

Z : ndarray: The linkage matrix in proper form (see the linkage function documentation).
rd : bool, optional: When False (default), a reference to the root ClusterNode object is returned. Otherwise, a tuple (r, d) is returned. r is a reference to the root node while d is a list of ClusterNode objects - one per original entry in the linkage matrix plus entries for all clustering steps. If a cluster id is less than the number of samples n in the data that the linkage matrix describes, then it corresponds to a singleton cluster (leaf node). See linkage for more information on the assignment of cluster ids to clusters.

Returns

tree : ClusterNode or tuple (ClusterNode, list of ClusterNode): If rd is False, a ClusterNode. If rd is True, a list of length 2*n - 1, with n the number of samples. See the description of rd above for more details.

Notes

Array API Standard Support

to_tree has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

====================  ====================  ====================
Library               CPU                   GPU
====================  ====================  ====================
NumPy                 ✅                     n/a                 
CuPy                  n/a                   ✅                   
PyTorch               ✅                     ✅                   
JAX                   ⚠️ no JIT             ⚠️ no JIT           
Dask                  ⚠️ computes graph     n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

Examples

import numpy as np
from scipy.cluster import hierarchy
rng = np.random.default_rng()
x = rng.random((5, 2))
Z = hierarchy.linkage(x)
hierarchy.to_tree(Z)
rootnode, nodelist = hierarchy.to_tree(Z, rd=True)
rootnode
len(nodelist)

✓

Aliases

scipy.cluster.hierarchy.to_tree