/sc-metacell

name: sc-metacell
description: Load when aggregating single cells into metacells (sample-aware coarse-grained pseudo-cells)
  on a normalised scRNA AnnData via SEACells or KMeans on a low-D embedding. Skip when ranking marker
  genes per cluster (use sc-markers); trajectory pseudotime ordering (use sc-pseudotime).
tags:
- singlecell
- scrna
- metacell
- seacells
- aggregation
- pseudo-cells

sc-metacell

Use from a step

aggregation = load_skill("sc-metacell")
cells = read_input("clustered.h5ad")
metacells = aggregation.metacells(cells, method="kmeans", n_metacells=30)
write_output(aggregation.cell_to_metacell(cells), "tables/cell_to_metacell.csv")
write_output(aggregation.metacell_summary(metacells), "tables/metacell_summary.csv")
write_output(metacells, "intermediate/metacells.h5ad")

The input receives obs['metacell']; the returned AnnData contains the aggregates. See `examples/example_step.py` for a PBMC example.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`metacells(adata, *, method: str='seacells', use_rep: str='X_pca', n_metacells: int=30, min_iter: int=10, max_iter: int=30, n_neighbors: int=15, n_pcs: int=20, random_state: int=0, celltype_key: str='leiden')`

Annotate input cells and return a new mean-expression metacell AnnData.

KMeans uses the selected embedding. SEACells falls back to KMeans only when its package cannot be imported; a warning and run_info identify the fallback. Runtime errors propagate. Counts are averaged, not summed, using layers['counts'] when present, else X. Input X is preserved; obs['metacell'] receives the assignments.

:param method: seacells (default) or kmeans. :param use_rep: Existing embedding, default X_pca. :param n_metacells: Requested aggregates, default 30; at least 2 and fewer than cells. :param min_iter: SEACells minimum fitting iterations, default 10. :param max_iter: SEACells maximum fitting iterations, default 30. :param n_neighbors: Neighbor count for SEACells when its graph is absent, default 15. :param n_pcs: PCs for that graph, default 20. :param random_state: Seed for KMeans and SEACells initialization, default 0. :param celltype_key: SEACells dominant-celltype annotation, default leiden. KMeans retains the legacy dominant_label from the first obs column. :returns: A new AnnData with mean_expression layer, n_cells and dominant_label. :raises ValueError: The method, embedding or numerical parameters are invalid.

`aggregate_metacells(adata, labels: pd.Series | None=None)`

Return mean-expression aggregates for labels, or the input obs['metacell'].

Labels must cover every cell. Prefer layers['counts'] over X. This is not a summed pseudobulk matrix and does not infer biological replicates.

`run_info(madata, *, keep: bool=True) -> dict`

Read requested/executed method and aggregation diagnostics from the result.

`metacell_summary(madata) -> pd.DataFrame`

Return a copy of the aggregate's size and dominant-label metadata.

`cell_to_metacell(adata) -> pd.DataFrame`

Return cell and metacell columns from the annotated input AnnData.

`size_distribution_figure(madata)`

Return a matplotlib Figure of cells per metacell.

<!-- api:end -->

Methods and parameters

`method="seacells"` retains the CLI default. If SEACells is unavailable, the API warns, uses KMeans and records both methods in `run_info`. Other backend errors propagate. `method="kmeans"` avoids that optional dependency.

Defaults remain `use_rep="X_pca"`, `n_metacells=30`, `min_iter=10`, `max_iter=30`, `n_neighbors=15` and `n_pcs=20`. KMeans uses the selected embedding, not a newly constructed neighbor graph. `random_state=0` seeds KMeans and now also SEACells initialization; the wrapper previously ignored the seed for SEACells.

Gotchas

• Aggregation takes the **mean**, not sum, of counts-layer values or X.

This is not sample-level pseudobulk, and grouping is not sample-aware (`_api.py:82`).

• The legacy KMeans `dominant_label` uses the first obs column, not

`celltype_key`; that option controls SEACells' extra dominant-celltype column (`_api.py:15`).

• `run_info(metacells)` reports fallback and expression source. Inspect

`aggregation="mean"` before feeding an aggregate into a count-based model (`_api.py:94`).

• CLI `processed.h5ad` contains original cells plus labels.

`tables/metacells.h5ad` is the aggregate; use it explicitly when needed.

Inputs & Outputs

Input needs the selected embedding and more cells than requested aggregates. The API returns a new metacell AnnData and table/Figure helpers.

CLI files: `processed.h5ad`, its `metacells_annotated.h5ad` alias, `tables/metacells.h5ad`, `tables/metacell_summary.csv`, `tables/cell_to_metacell.csv`, `report.md`, `result.json`, `figures/metacell_centroids.png` and `figures/metacell_size_distribution.png`. Plot data/manifests and optional R-enhanced figures are also exported.

Key CLI

python skills/singlecell/scrna/sc-metacell/sc_metacell.py --demo --method kmeans --output /tmp/sc_metacell_demo
python skills/singlecell/scrna/sc-metacell/sc_metacell.py --input clustered.h5ad --method kmeans --n-metacells 30 --output results/

Dependencies

`anndata`, `matplotlib`, `numpy`, `pandas`, `scanpy`, `scikit-learn`, `scipy`, `SEACells`