mantispy.tl.cluster

mantispy.tl.cluster(adata, use_rep='X_pca', method='hierarchical', linkage='average', metric='correlation', distance_cut=None, n_clusters=None, criterion='silhouette', resolution=1.0, key_added='cluster', copy=False, *, stability_window=None)

Cluster the profiles and store the labels, with the linkage tree for a dendrogram.

Parameters:

adata AnnData

Profiles to cluster, normally one consensus profile per perturbation from consensus().

use_rep str | None (default: 'X_pca')

Cluster obsm[use_rep] (an embedding such as pca() writes) instead of X, or None for X.

method str (default: 'hierarchical')

"hierarchical" (the default) builds a linkage tree with scipy; "leiden" delegates to scanpy.tl.leiden() on the neighbors graph and stores no tree.

linkage str (default: 'average')

The scipy linkage method for method="hierarchical", for example "average", "complete" or "ward".

metric str (default: 'correlation')

The scipy pairwise distance for method="hierarchical". "correlation" is 1 - Pearson between profiles.

distance_cut float | None (default: None)

Cut the tree at this height. Mutually exclusive with n_clusters; method="hierarchical" only.

n_clusters int | None (default: None)

Cut the tree into this many clusters. Mutually exclusive with distance_cut; method="hierarchical" only.

criterion Literal['silhouette', 'stability'] (default: 'silhouette')

Which score picks the automatic cut for method="hierarchical": "silhouette" (the default) keeps the cut with the best silhouette, "stability" keeps the cut whose cluster membership is most stable across nearby heights. Ignored when distance_cut or n_clusters is given, or when method != "hierarchical".

resolution float (default: 1.0)

Passed to scanpy.tl.leiden() for method="leiden".

key_added str (default: 'cluster')

obs column the labels are written to.

copy bool (default: False)

Return a modified copy instead of mutating in place.

stability_window tuple[float, float] | None (default: None)

Optional (low, high) height band the criterion="stability" sweep is restricted to, in the same height units as distance_cut (for metric="correlation", height is 1 - correlation, so the correlation window 0.4 to 0.7 is (0.3, 0.6)). None (the default) sweeps the full height range. Whenever provided it is validated for shape; it is only applied to the criterion="stability" automatic cut.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes categorical cluster labels to obs[key_added]. For method="hierarchical" it also writes the linkage matrix to uns["mantispy"][key_added + "_linkage"] and, to uns["mantispy"][key_added], a summary with n_clusters, distance_cut, metric, linkage, silhouette, stability and the labels the tree’s leaves carry, in the object’s row order, so dendrogram() can label them. silhouette is set only when the automatic criterion="silhouette" cut ran. stability is set when the criterion="stability" auto-cut selects an in-range cut, and stays nan on the degenerate fallback (a flat tree or no in-range cut). The score that did not run stays nan.

Raises:

ValueError – method is not one of METHODS, both distance_cut and n_clusters are given, criterion is not "silhouette" or "stability", stability_window is not a length-2 (low, high) pair of numbers with low < high or does not overlap the tree’s height range, or the object has fewer than two rows to cluster.

Notes

With neither distance_cut nor n_clusters the granularity is chosen automatically. With criterion="silhouette" the tree is cut into 2 to min(n_obs - 1, 25) clusters and the cut with the best silhouette is kept. With criterion="stability" a grid of cut heights is swept and the height whose cluster membership recurs most at neighboring heights is kept, the way Rohban 2017 cut their dendrogram. Pass stability_window to restrict that sweep to a height band, so the wide plateau of a few huge clusters near the top of the tree cannot trivially win and collapse the cut; it only affects criterion="stability". Within a window the criterion favors the finest perfectly-stable cut, since the exact-membership stability saturates to 1.0 across a stable plateau. With a window the sweep is bounded at both ends by the window rather than by the min(n_obs - 1, 25) cluster ceiling, so a windowed stability cut may return more than 25 clusters; only the two-or-more-clusters floor is kept, so set the window low edge above the near-singleton region of the tree or a near-singleton cut can be selected. Rank clusters by the biology they recover rather than trusting the count, since neither score sees biology.