sc-consensus-clustering

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

1. Plan members — either user-supplied (--members / --all) or derived from the resolution sweep × cluster-methods combinations.
2. Fan out — runtime invokes sc-clustering once per member.
3. Score — silhouette_score from each member's clustering_summary.csv is the intrinsic-quality signal; cross-method NMI is computed across members.
4. BC pick — top-K-by-composite-score default; CLI interactive override allowed.
5. Consensus — kmode / weighted / LCA on the selected base clusterings.
6. 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

# Default sweep (leiden at 5 resolutions)
oc run sc-consensus-clustering --input preprocessed.h5ad --output out/

# Both methods × 5 resolutions = 10 members; SACCELERATOR-style benchmark
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

# Explicit
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