Single-Cell Metacell

Why This Exists

• Without it: large noisy single-cell datasets are hard to summarize stably.
• With it: cells are compressed into metacell-level profiles for downstream DE, trajectory, and visualization.

Data / State Requirements

• Input matrix: normalized expression in adata.X (log-normalized preferred)
• Raw counts: adata.layers["counts"] is used for metacell aggregation when available; otherwise adata.X is used
• Embedding: adata.obsm["X_pca"] (or another embedding specified via --use-rep) must exist
• Neighbors graph: required for SEACells; computed automatically if missing
• Upstream step: run sc-preprocessing first to obtain normalized expression + PCA

Current Methods

Method	When to use	Needs neighbors?	Example
seacells	Structure-aware aggregation; preserves manifold topology	Yes (auto-computed)	--method seacells
kmeans	Lightweight baseline; fast compression	No	--method kmeans

Key Parameters

Parameter	Meaning	Default
--method	seacells or kmeans	seacells
--use-rep	embedding in adata.obsm used for aggregation	X_pca
--n-metacells	target metacell count (must be < n_cells)	30
--celltype-key	label column for dominant-type summary (SEACells)	leiden
--min-iter / --max-iter	SEACells optimization iteration bounds	10 / 30
--seed	random seed for reproducibility	0

Workflow

1. Load data (--input or --demo)
2. Preflight: validate embedding, n_metacells, matrix semantics
3. Run metacell construction (SEACells or k-means)
4. Assign metacell labels to original cells
5. Aggregate expression per metacell
6. Render gallery (centroid plot, size distribution)
7. Export processed.h5ad (original cells + metacell labels + contracts)

Outputs

File	Description
processed.h5ad	Original cell-level object with obs["metacell"] assignment and OmicsClaw contracts
tables/metacells.h5ad	Aggregated metacell expression profiles
tables/cell_to_metacell.csv	Cell-to-metacell mapping
tables/metacell_summary.csv	Metacell-level summary (n_cells, dominant label)
figures/metacell_centroids.png	Centroid overlay on embedding
figures/metacell_size_distribution.png	Histogram of cells per metacell
figures/manifest.json	Figure manifest for gallery rendering
figure_data/manifest.json	Plot-ready data manifest
report.md	Human-readable analysis report
result.json	Machine-readable result envelope

Matrix Contract (Output)

• X = normalized_expression
• layers["counts"] = raw_counts (when available from input)
• raw = raw_counts_snapshot (when available from input)
• producer_skill = sc-metacell

Usual Next Steps

After metacell construction, common next steps include:

• Differential expression (sc-de) on metacell-level profiles
• Trajectory analysis (sc-pseudotime) using metacell-smoothed data
• Visualization of metacell-level gene expression patterns

References Inside OmicsClaw

• For short execution guardrails, see knowledge_base/knowhows/KH-sc-metacell-guardrails.md.
• For longer method and interpretation guidance, see knowledge_base/skill-guides/singlecell/sc-metacell.md.

CLI Parameters

Flag	Type	Default	Description	Validation
--input	str	None	Input AnnData file (.h5ad)	Required unless --demo
--output	str	—	Output directory	Required
--demo	flag	off	Run with built-in demo data	—
--method	str	seacells	Metacell construction method: seacells or kmeans	Choices: seacells, kmeans; falls back to kmeans if SEACells not installed
--use-rep	str	X_pca	Embedding in adata.obsm to use for aggregation	Must exist in adata.obsm
--n-metacells	int	30	Target number of metacells	Must be >= 2 and < n_cells
--celltype-key	str	leiden	adata.obs column used for dominant-type summary (SEACells)	—
--min-iter	int	10	Minimum SEACells optimization iterations	Must be >= 1; must be <= --max-iter
--max-iter	int	30	Maximum SEACells optimization iterations	Must be >= --min-iter
--seed	int	0	Random seed for reproducibility	—
--n-neighbors	int	15	Neighbors for SEACells graph construction	Must be >= 2
--n-pcs	int	20	PCs used for SEACells neighbor computation	Must be >= 1
--r-enhanced	flag	off	Generate R Enhanced plots (requires R + ggplot2)	—

R Enhanced Plots

Renderer	Output file	Description
plot_embedding_discrete	figures/r_enhanced/r_embedding_discrete.png	Embedding colored by metacell assignment
plot_embedding_feature	figures/r_enhanced/r_embedding_feature.png	Embedding colored by a continuous feature
plot_cell_barplot	figures/r_enhanced/r_cell_barplot.png	Bar chart of cells per metacell

Workflow Position

Upstream: sc-clustering or sc-cell-annotation Downstream: sc-de, sc-enrichment (using metacell AnnData)