leiden-clustering-resolution-optimization

leiden-clustering-resolution-optimization

Summary

Apply Leiden clustering to single-cell omics data (ATAC-seq, RNA-seq, Hi-C, methylation) with parameter tuning to identify optimal resolution values that yield biologically meaningful cluster assignments. This skill involves running the tl.leiden method on spectral embeddings and validating cluster quality through comparison with reference assignments or biological interpretation.

When to use

You have performed spectral dimension reduction on single-cell omics count matrices and wish to partition cells into discrete populations. Use this skill when you need to discover cell types or states and want to systematically evaluate whether the chosen resolution produces clusters that align with known cell annotations, downstream peak calling results, or biological markers.

When NOT to use

• Input is already annotated with ground-truth cell types and downstream biological validation is unnecessary.
• The analysis goal is to identify rare cell populations where you require soft clustering probabilities rather than hard assignments.
• Data has been pre-processed with a different clustering method (e.g., k-means or hierarchical clustering) and you are not re-optimizing.

Inputs

• spectral eigenvector matrix (output from tl.spectral or tl.multi_spectral) embedded in AnnData .obsm
• AnnData object containing the embedding

Outputs

• cluster assignment vector (integer categorical in AnnData .obs)
• UMAP coordinates for visualization (in .obsm)

How to apply

Run tl.leiden on the spectral eigenvectors or other embedding matrix with the default resolution parameter as a starting point. The Leiden algorithm optimizes community detection by repeatedly merging and splitting partitions to maximize modularity. Compare the resulting cluster assignments and UMAP/embedding coordinates against reference annotations or expected cell type markers. If clusters appear over-fragmented or merged incorrectly, iterate resolution upward (finer granularity) or downward (coarser granularity). Validate by checking whether downstream analyses—such as peak calling grouped by cluster, or differential feature analysis—produce biologically coherent results. The article demonstrates this workflow on the pbmc10k_multiome dataset, where Leiden clustering on spectral embeddings successfully recovers documented PBMC subpopulations.