Skip to content

ClusterTree 

ClusterTree(
    labels: tuple[str, ...],
    merge: tuple[tuple[int, int], ...],
    height: tuple[float, ...],
    order: tuple[int, ...],
    method: str | None = None,
    distance: str | None = None,
)

A clustering tree in R's hclust layout.

Build it with :func:hclust or :meth:ClusterTree.from_linkage.

Parameters:

  • labels (tuple of str) –

    Leaf names, in input order.

  • merge (tuple of (int, int)) –

    One pair per merge: -k is leaf k (1-based), +s the cluster made at step s (1-based), as R's merge.

  • height (tuple of float) –

    Height of each merge.

  • order (tuple of int) –

    Leaves (0-based indices into labels) from left to right; R's order minus one.

  • method (str or None, default: None ) –

    Linkage used, when known.

  • distance (str or None, default: None ) –

    Distance used, when known.

Examples:

>>> from ggrust import hclust
>>> tree = hclust({"name": ["a", "b", "c"], "v": [0.0, 1.0, 5.0]}, labels="name")
>>> tree.ordered_labels
('c', 'a', 'b')
>>> tree.height
(1.0, 5.0)

ordered_labels property 

ordered_labels

Leaf names from left to right (the axis order of scale_*_dendro()).

from_linkage classmethod 

from_linkage(
    linkage: Sequence[Sequence[float]],
    labels: Sequence[str],
    *,
    order: Sequence[int] | None = None,
) -> ClusterTree

Read a SciPy linkage matrix (scipy.cluster.hierarchy.linkage).

Parameters:

  • linkage (array-like of shape (n - 1, 4)) –

    SciPy linkage rows [a, b, height, count]: indices below n are leaves, n + s the cluster of row s.

  • labels (sequence of str) –

    Leaf names, one per observation.

  • order (sequence of int, default: None ) –

    Leaf order (0-based). Default: SciPy's dendrogram() order (each merge's first side before its second, its leaves), so scanpy trees keep their categories_ordered.

Returns:

Raises:

  • SpecError –

    If linkage is not a valid (n - 1) x 4 SciPy linkage of labels (the error names the row and column), or labels repeat.

Examples:

A scanpy tree (scanpy.tl.dendrogram) is reused as it is:

>>> import ggrust as gg
>>> def scanpy_tree(adata, group_by):
...     info = adata.uns[f"dendrogram_{group_by}"]
...     labels = adata.obs[group_by].cat.categories
...     return gg.ClusterTree.from_linkage(info["linkage"], labels)

>>> from ggrust import ClusterTree
>>> tree = ClusterTree.from_linkage([[0, 1, 1.0, 2], [2, 3, 4.0, 3]], ["a", "b", "c"])
>>> tree.merge
((-1, -2), (-3, 1))
>>> tree.ordered_labels
('c', 'a', 'b')

to_dict 

to_dict() -> dict[str, Any]

Return the tree as the plot spec stores it.

Returns:

  • dict –

    labels, merge (list of pairs), height and order.