/sc-multi-count

name: sc-multi-count
description: Load when merging multiple single-sample scRNA-seq count matrices (one per sample-from-sc-count)
  into a single downstream-ready AnnData with sample labels. Skip when input is one already-merged AnnData
  (use sc-standardize-input); FASTQ→counts on each sample (use sc-count).
trigger: merge count matrices, multi-sample count, aggregate samples, combine count outputs, cellranger aggr alternative
tags:
- singlecell
- scrna
- multi-sample
- merge
- aggregation

sc-multi-count

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output

merge = load_skill("sc-multi-count")
samples = [read_input("data/sample_a.h5ad"), read_input("data/sample_b.h5ad")]
adata = merge.merge_samples(samples, sample_ids=["sample_a", "sample_b"])
write_output(adata, "intermediate/merged.h5ad")
write_output(merge.per_sample_summary(adata), "tables/samples.csv")

The API returns objects and does not write files. Existing sample labels are kept even when `sample_ids` supplies different barcode prefixes. See `examples/example_step.py` for a count-conservation check using two halves of PBMC3k; those halves are demonstration samples, not biological replicates.

When to use

The user has run `sc-count` (or another counting backend) on multiple samples separately and now needs them merged into one AnnData with a canonical sample-label column for downstream batch-aware analysis. This only joins matrices; it does not perform Cell Ranger's depth normalization or recount reads.

Inputs & Outputs

**Inputs**

• Two or more AnnData objects with raw count-like values in `.X`; the CLI

takes repeated `--input` H5AD paths. Features are aligned by name.

**Outputs**

• `tables/barcode_metrics.csv`
• `tables/per_sample_summary.csv`
• `figures/barcode_rank.png`
• `figures/count_complexity_scatter.png`
• `figures/count_distributions.png`
• `figures/sample_composition.png`
• `processed.h5ad`
• `standardized_input.h5ad`
• `report.md`
• `result.json`
• `figures/manifest.json`, `figure_data/manifest.json` and copies of the two tables
• `reproducibility/commands.sh`, `reproducibility/requirements.txt`
• The returned AnnData has sample labels, `layers["counts"]` and a count snapshot in `.raw`.

Flow

1. Collect per-sample AnnData paths from each `--input <path>` flag (`action="append"`); paired `--sample-id <id>` flags assign sample labels. 2. Load and tag samples, preserving an existing `obs["sample_id"]`. 3. Join features and cells, zero-fill absent features, then record the count contract. 4. Write merged AnnData; emit per-sample / per-barcode summary tables. 5. Render barcode-rank + composition figures. 6. Emit `report.md` + `result.json`.

Gotchas

• **`--input` is `action="append"` — repeat the flag, do not comma-split.** `sc_multi_count.py` declares `--input` with `action="append"`. Pass `--input s1.h5ad --input s2.h5ad --input s3.h5ad`; a single comma-separated value (`--input s1.h5ad,s2.h5ad`) is treated as one literal path that does not exist and triggers `FileNotFoundError`. No directory expansion.
• **At least two `--input` paths are required.** `sc_multi_count.py` calls `parser.error("At least two --input paths required when not using --demo.")` if you pass zero or one. For a single-sample run you don't need this skill — just use the upstream `sc-count` output directly.
• **Missing input file → hard fail.** `sc_multi_count.py` raises `FileNotFoundError` when any individual `--input` path does not resolve. In batch pipelines, a single mistyped sample name aborts the whole merge — pre-flight your file list.
• **`--r-enhanced` is accepted but produces no R plots.** This skill emits Python figures only; the flag exists for CLI consistency.
• **No within-sample re-counting.** This is a stitching skill — it stacks already-canonical AnnData objects. If a per-sample input has a non-canonical matrix layout, run `sc-standardize-input` on each before this; otherwise the merged contract may surface incoherent per-cell metrics downstream.
• `_api.py:merge_samples` does not validate integer counts. It labels `.X` and its copies as raw counts; passing normalized data gives a misleading matrix contract.
• `_api.py:merge_samples` keeps existing sample labels. `--sample-id` changes barcode prefixes but does not replace an existing `sample_id` column; check `tables/per_sample_summary.csv`.
• `sc_multi_count.py:_demo_adata` ignores `--sample-id` in demo mode. Its labels stay `sample_A` and `sample_B`.

Key CLI

# Demo (two halves of PBMC3k raw counts)
python skills/singlecell/scrna/sc-multi-count/sc_multi_count.py --demo --output /tmp/sc_multi_demo

# Three samples — repeat --input per file
python skills/singlecell/scrna/sc-multi-count/sc_multi_count.py \
  --input s1.h5ad --input s2.h5ad --input s3.h5ad \
  --output results/

# With explicit per-sample labels (paired with --input order)
python skills/singlecell/scrna/sc-multi-count/sc_multi_count.py \
  --input s1.h5ad --sample-id ctrl_a \
  --input s2.h5ad --sample-id ctrl_b \
  --input s3.h5ad --sample-id treat_a \
  --output results/

API

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

`merge_samples(adatas, *, sample_ids=None, sample_key='sample_id', join='outer')`

Merge .X counts, align features and return a standardized copy.

Inputs are not modified. Missing features in an outer join become zeros. Existing sample labels are kept; sample_ids supplies missing labels and, when given, prefixes each input's barcodes. With no IDs, existing barcodes are kept and duplicate names get numeric suffixes; missing sample labels become sample_1, sample_2, etc. Like the CLI, this does not test whether .X holds integer counts. Standardize external inputs before merging them.

`barcode_metrics(adata, *, sample_key='sample_id')`

Return per-barcode .X counts and detected features, sorted by total counts.

`per_sample_summary(adat