to_tree — SciPy v1.16.0 Manual (original) (raw)

scipy.cluster.hierarchy.

scipy.cluster.hierarchy.to_tree(Z, rd=False)[source]#

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

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:

Zndarray

The linkage matrix in proper form (see the linkagefunction documentation).

rdbool, 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 ClusterNodeobjects - 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:

treeClusterNode 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

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.

See Support for the array API standard 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) <scipy.cluster.hierarchy.ClusterNode object at ... rootnode, nodelist = hierarchy.to_tree(Z, rd=True) rootnode <scipy.cluster.hierarchy.ClusterNode object at ... len(nodelist) 9