| name | sc-consensus-clustering |
| description | Multi-resolution typed consensus over sc-clustering. Fans out leiden / louvain at several resolutions in parallel, scores members by silhouette + cross-method NMI, runs kmode / weighted / LCA consensus on the surviving base clusterings, and emits a verified report carrying the mandatory A-path banner per ADR 0010. |
| version | 0.1.0 |
| author | OmicsClaw |
| license | Apache-2.0 |
| tags | ["singlecell","consensus","typed-consensus","multi-resolution","silhouette","bc-ranking","kmode","lca","weighted"] |
| requires | ["anndata","scanpy","numpy","pandas","scipy","scikit-learn","pyyaml"] |
sc-consensus-clustering
When to use
The user has a preprocessed scRNA AnnData (PCA + neighborhood graph
already computed via sc-preprocessing) and wants robust cell-cluster
assignments insensitive to the chosen resolution. Single-resolution
Leiden/Louvain results are notoriously resolution-sensitive — at
r=0.4 you get 6 broad types, at r=1.5 you get 22 sub-states. This
skill runs a SACCELERATOR-style consensus across a resolution sweep
(and optionally across leiden vs louvain) and reports the stable
core of the labels.
It does NOT replace sc-clustering; it wraps it.
Inputs & Outputs
| Input | Format | Required |
|---|
| Preprocessed AnnData | --input <preprocessed.h5ad> (with obsm["X_pca"]) | yes |
| Output directory | --output <dir> | yes |
| Resolutions to sweep | --resolutions 0.4,0.8,1.0,1.4,2.0 | no (default 0.5,0.8,1.0,1.4,2.0) |
| Cluster methods to use | --cluster-methods leiden,louvain | no (default leiden) |
| Explicit member list | --members leiden:resolution=0.5,louvain:resolution=1.0 | no (overrides the sweep) |
| Fan-out everything | --all | no (sweeps both methods × all default resolutions) |
| Operator | --operator {kmode,weighted,lca} | no (default kmode) |
| Score weights | --alpha 0.6 --beta 0.4 | no (ADR 0011 defaults) |
| Class-imbalance cap | --max-class-frac 0.8 | no |
| Pre-run plan confirm | --confirm-plan | no |
| Non-interactive | --non-interactive | no |
| Seed | --seed 0 | no |
| Output | Path | Notes |
|---|
| Verified consensus labels | consensus_labels.tsv | columns cell_id,consensus_<operator> |
| Per-member labels | member_<name>/figure_data/embedding_points.csv | from sc-clustering |
| Cross-method NMI matrix | cross_method_nmi.csv | square per member |
| Composite scores | member_scores.csv | ADR 0011 schema |
| Markdown report | report.md | starts with [A: Verified consensus] (non-configurable) |
| Audit | plan.json | resolution sweep + chosen operator + filtered members |
Flow
- Plan members — either user-supplied (
--members / --all) or
derived from the resolution sweep × cluster-methods combinations.
- Fan out — runtime invokes
sc-clustering once per member.
- Score —
silhouette_score from each member's
clustering_summary.csv is the intrinsic-quality signal; cross-method
NMI is computed across members.
- BC pick — top-K-by-composite-score default; CLI interactive
override allowed.
- Consensus — kmode / weighted / LCA on the selected base
clusterings.
- Report — banner + score table + NMI matrix.
Gotchas
--cluster-methods defaults to leiden ONLY, not both, because
louvain and leiden agree to within 1–2% on most datasets and the
consensus signal comes mostly from the resolution sweep.- Resolutions must span at least one factor of 2 for the consensus
to be informative; default sweep covers 0.5–2.0.
- The mandatory banner is enforced by
runtime/consensus/dispatch.output_banner. Do NOT strip it.
requires_preprocessed: true — run sc-preprocessing first.
Key CLI
oc run sc-consensus-clustering --input preprocessed.h5ad --output out/
oc run sc-consensus-clustering --input preprocessed.h5ad --output out/ \
--cluster-methods leiden,louvain --resolutions 0.5,0.8,1.0,1.4,2.0
oc run sc-consensus-clustering --input preprocessed.h5ad --output out/ \
--members leiden:resolution=0.5,leiden:resolution=1.0,louvain:resolution=1.0
Pointers
- ADR 0010 — runtime architecture
- ADR 0011 — scoring + evaluation
skills/spatial/consensus-domains/ — sibling spatial-side skill
