sc-clustering

sc-clustering

When to use

The user has a normalised AnnData with PCA / integrated embedding already populated and wants the standard scRNA neighbour-graph → embedding → cluster workflow. Combinable in one call: pick an embedding method (umap default, also tsne / diffmap / phate) and a clustering method (leiden default, also louvain), with an explicit resolution or auto-resolution search. Reads from obsm["X_pca"] / obsm["X_harmony"] / etc. via use_rep.

Use from a step

clustering = load_skill("sc-clustering")
adata = read_input("results/02_preprocess/intermediate/adata_preprocessed.h5ad")
# resolution 0.8: the user wants broad cell types; sc-clustering's default is 1.0.
adata = clustering.cluster(adata, resolution=0.8)
write_output(clustering.cluster_summary(adata, key="leiden"), "tables/cluster_summary.csv")
write_output(clustering.embedding_figure(adata, color="leiden"), "figures/umap_leiden.png")
write_output(adata, "intermediate/adata_clustered.h5ad")

A complete step that runs on demo data: examples/example_step.py.

API

cluster(adata, *, use_rep: str | None=None, use_existing_graph: bool=False, n_neighbors: int=15, n_pcs: int=50, embedding: str='umap', method: str='leiden', resolution: float=1.0, random_state: int=0, umap_min_dist: float=0.5, umap_spread: float=1.0, tsne_perplexity: float=30.0, tsne_metric: str='euclidean', diffmap_n_comps: int=15, phate_knn: int=15, phate_decay: int=40)

Build the neighbour graph, cluster the cells and compute a 2-D embedding, in place.

Writes obs[method] (the cluster labels, a categorical of strings), obsm['X_<embedding>'], the graph in obsp and uns['neighbors'], and records the cluster key as the primary one in the matrix contract.

:param use_rep: The obsm key the graph is built on. Default None: the first of X_pca, X_harmony, X_scvi, X_scanvi, X_scanorama present. Pass X_harmony or X_scvi after batch integration. :param n_neighbors: Neighbours per cell in the graph. Default 15, scanpy's default. Larger values give smoother, coarser structure. :param use_existing_graph: Keep the graph in uns['neighbors'] and obsp instead of rebuilding it. Default False; set True after BBKNN. Graph construction parameters are then ignored; UMAP and diffusion maps use the retained graph, while t-SNE and PHATE still use use_rep. :param n_pcs: Components of use_rep to use. Default 50; pick it from sc-preprocessing's pca_variance_table (the elbow) when the data are small. :param embedding: "umap" (default), "tsne", "diffmap" or "phate". :param method: "leiden" (default) or "louvain"; also the obs column written. :param resolution: Clustering resolution. Default 1.0, scanpy's default. Lower it (0.3 to 0.6) for broad cell types, raise it for finer subtypes; or use :func:auto_resolution. :param random_state: Seed for the graph, the clustering and the embedding. Default 0, scanpy's default, which makes reruns reproduce the labels. :param umap_min_dist: UMAP min_dist. Default 0.5, scanpy's default. :param umap_spread: UMAP spread. Default 1.0, scanpy's default. :param tsne_perplexity: t-SNE perplexity. Default 30. :param tsne_metric: t-SNE distance metric. Default "euclidean". :param diffmap_n_comps: Diffusion-map components. Default 15. :param phate_knn: PHATE neighbours. Default 15. :param phate_decay: PHATE alpha decay. Default 40. :returns: The same AnnData. :raises ValueError: no embedding is available, or an unknown method or embedding.