scanpy.tl.dendrogram

scanpy.tl.dendrogram(adata, groupby, *, n_pcs=None, use=None, var_names=None, use_raw=None, cor_method='pearson', linkage_method='complete', optimal_ordering=False, out=False, key_added=None, use_rep=None, inplace=True)

Compute a hierarchical clustering for the given groupby categories.

By default, the PCA representation is used unless .X has less than 50 variables.

Alternatively, a list of var_names (e.g. genes) can be given.

Average values of either var_names or components are used to compute a correlation matrix.

The hierarchical clustering can be visualized using scanpy.pl.dendrogram() or multiple other visualizations that can include a dendrogram: matrixplot(), heatmap(), dotplot(), and stacked_violin().

Note

The computation of the hierarchical clustering is based on predefined groups and not per cell. The correlation matrix is computed using by default pearson but other methods are available.

Array type support

Array type	supported	… experimentally in dask Array
numpy.ndarray	✅	❌
scipy.sparse.{csr,csc}_{array,matrix}	✅	❌

Parameters:

adata AnnData

Annotated data matrix

groupby AdRef | str | Sequence[AdRef | str]

The observations grouping(s) to cluster. Given by references like A.obs['leiden'], or by column names (strs are resolve()d with ScanpyV2Preview).

n_pcs int | None (default: None)

Use this many PCs. If n_pcs==0 use .X if use is None.

use LayerAcc | MultiAcc | str | None (default: None)

Use the indicated representation: a LayerAcc (e.g. A.X, A.layers[...]) or MultiAcc (e.g. A.obsm[...]). strs are resolve()d, e.g. 'obsm.pca'.

If None, the representation is chosen automatically: For .n_vars < N_PCS (default: 50), .X is used, otherwise the PCA representation (.obsm['X_pca'], or .obsm['pca'] if it was computed under ScanpyV2Preview). If it is not present, it’s computed with default parameters or n_pcs if present.

use_rep str | None (default: None)

Deprecated since version 1.13.0: Use use instead.

'X' or a key of obsm, i.e. use_rep='k' is use=A.obsm['k'] and use_rep='X' is use=A.X.

var_names Sequence[str] | None (default: None)

List of var_names to use for computing the hierarchical clustering. If var_names is given, then use and n_pcs are ignored.

use_raw bool | None (default: None)

Deprecated since version 1.13.0: raw is deprecated. Keep the data in a layer instead.

Only when var_names is not None. Use raw attribute of adata if present.

cor_method str (default: 'pearson')

Correlation method to use. Options are ‘pearson’, ‘kendall’, and ‘spearman’

linkage_method str (default: 'complete')

Linkage method to use. See scipy.cluster.hierarchy.linkage() for more information.

optimal_ordering bool (default: False)

Same as the optimal_ordering argument of scipy.cluster.hierarchy.linkage() which reorders the linkage matrix so that the distance between successive leaves is minimal.

out bool (default: False)

Where to write the dendrogram information. If True, the dendrogram information is returned instead of written. If False, it is written to .uns[f'dendrogram_{groupby}'] (with groupby joined by _).

key_added str | None (default: None)

Name of the uns entry to write to instead (until there are .uns accessors).

inplace bool (default: True)

Deprecated since version 1.13.0: Use out=True instead of inplace=False.

inplace=False is out=True.

Return type:

dict[str, Any] | None

Returns:

Returns a dict with dendrogram information if out=True, else None. Sets the following field:

adata.uns[f'dendrogram_{groupby}' | key_added]dict

Dendrogram information.

Examples

>>> import scanpy as sc
>>> adata = sc.datasets.pbmc68k_reduced()
>>> sc.tl.dendrogram(adata, groupby="bulk_labels")
>>> sc.pl.dendrogram(adata, groupby="bulk_labels")
<Axes: >
>>> markers = ["C1QA", "PSAP", "CD79A", "CD79B", "CST3", "LYZ"]
>>> sc.pl.dotplot(adata, markers, groupby="bulk_labels", dendrogram=True)