scroma 0.3.0

Batch-aware SVD-based pathway-activity inference and a ground-truth simulation framework for single-cell transcriptomics

scROMA

Batch-aware, SVD-based pathway-activity inference for single-cell transcriptomics, natively integrated with the Scanpy/AnnData ecosystem. scROMA is a Python implementation of ROMA (Representation and Quantification Of Module Activity) that scores each gene set from the coordinated variation among its member genes, with per-cell activity scores, per-gene contributions, and permutation-based significance. Its batch-aware extension corrects technical variation inside the gene-set subspace rather than across the whole transcriptome, and it ships with a generative simulation framework that produces data with fully specified ground-truth pathway activity.

Install

pip install scroma
# or with uv:
uv pip install scroma      # into the active environment
uv add scroma              # into a uv project

Requires Python ≥ 3.10 and anndata ≥ 0.12. Tutorial datasets download on first use (via pooch).

Quick start

import scroma

# --- core pathway-activity scoring ---
adata = scroma.datasets.pbmc3k()          # downloaded + cached on first use
roma = scroma.ROMA()
roma.adata = adata
roma.gmt   = scroma.use_hallmarks()       # bundled MSigDB Hallmark gene sets
roma.compute()
roma.summary()                            # significantly active pathways

# --- batch-aware scoring (correction within the gene-set subspace) ---
broma = scroma.BatchAwareROMA()
broma.adata = adata
broma.gmt   = scroma.use_hallmarks()
broma.compute(batch_key="batch", batch_method="harmonylike")

# --- simulation with ground-truth pathway activity ---
sim = scroma.simulate(n_batches=3, seed=42)        # AnnData + ground truth in .obsm/.uns
reps = scroma.load_benchmark("multi")              # 10 default benchmark replicates

Features

• Two complementary scores per gene set: an L1 overdispersion score and a median-expression shift score, plus per-cell activity scores and per-gene contribution weights.
• Permutation significance with Benjamini–Hochberg correction.
• Batch-aware correction within each gene set (residualized, contrastive, weighted, centered, ComBat, MNN, harmonylike).
• Ground-truth simulator (scroma.simulate / scroma.load_benchmark) for quantitative benchmarking.
• Bundled gene sets (use_hallmarks, use_reactome, use_progeny) and one-call tutorial datasets (datasets.pbmc3k, datasets.pbmc_ifnb).

Documentation

Full docs and tutorials: https://scroma.readthedocs.io

• Getting started — scoring pathway activity on PBMCs
• Simulated data — visualising ground truth and computing AUROC
• Gene-set weights — which genes drive a pathway
• Pathway-activity clustermap

Citing scROMA

If you use scROMA, please cite the paper (see CITATION.cff).

License

scROMA is released under the GNU GPL v3.