| name | clustering-quality |
| description | Assess single-cell clustering quality using silhouette score, modularity, and phiclust. Returns recommendations to adjust resolution or accept current clustering. |
| allowed-tools | Read, Bash |
| compatibility | scRNA-seq, snRNA-seq |
Clustering Quality Assessment
When to Use
After running Leiden or Louvain clustering on single-cell data. Use before cell type annotation to ensure cluster boundaries are biologically meaningful.
Tools
silhouette_check(adata, cluster_key, use_rep)
Computes Average Silhouette Width (ASW) on the PCA embedding.
- ASW > 0.5: clear cluster structure
- ASW 0.25-0.5: moderate
- ASW < 0.25: recommend adjusting resolution
Returns: {"tool": "silhouette", "asw": float, "per_cluster": dict, "recommendation": str, "details": str}
modularity_check(adata, cluster_key)
Computes graph modularity on the connectivities graph.
- Modularity > 0.3: meaningful community structure
- Modularity > 0.5: strong community structure
- Modularity < 0.2: recommend adjusting resolution
Requires adata.obsp["connectivities"] from sc.pp.neighbors().
Returns: {"tool": "modularity", "modularity": float, "recommendation": str, "details": str}
phiclust_check(adata, cluster_key)
R-based phi score analysis for hidden substructure. Requires rpy2.
- Phi > 0 for >50% of clusters: increase resolution
- No clusters with phi > 0: possible over-clustering
Decision Logic
Majority vote across available tools:
- If majority says "adjust": multiply resolution by 1.5 (if under-clustered) or 0.7 (if over-clustered)
- If majority says "ok": accept current clustering
- Resolution clamped to [0.05, 2.0]
