Metadata-Version: 2.4
Name: scroma
Version: 0.3.0
Summary: Batch-aware SVD-based pathway-activity inference and a ground-truth simulation framework for single-cell transcriptomics
Author-email: Altynbek Zhubanchaliyev <altynbek.zhubanchaliyev@curie.fr>
Maintainer-email: Altynbek Zhubanchaliyev <altynbek.zhubanchaliyev@curie.fr>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/altyn-bulmers/scroma
Project-URL: Documentation, https://scroma.readthedocs.io
Project-URL: Repository, https://github.com/altyn-bulmers/scroma
Project-URL: Issues, https://github.com/altyn-bulmers/scroma/issues
Keywords: bioinformatics,single-cell,scRNA-seq,pathway-activity,gene-set-analysis,batch-correction,SVD,simulation,scanpy,anndata
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.12
Requires-Dist: scanpy
Requires-Dist: scikit-learn
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: statsmodels
Requires-Dist: joblib
Requires-Dist: pooch
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# scROMA

[![PyPI](https://img.shields.io/pypi/v/scroma.svg)](https://pypi.org/project/scroma/)
[![Docs](https://readthedocs.org/projects/scroma/badge/?version=latest)](https://scroma.readthedocs.io/en/latest/)
[![CI](https://github.com/altyn-bulmers/scroma/actions/workflows/ci.yml/badge.svg)](https://github.com/altyn-bulmers/scroma/actions/workflows/ci.yml)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python](https://img.shields.io/pypi/pyversions/scroma.svg)](https://pypi.org/project/scroma/)

**Batch-aware, SVD-based pathway-activity inference for single-cell transcriptomics**, natively
integrated with the [Scanpy](https://scanpy.readthedocs.io)/[AnnData](https://anndata.readthedocs.io)
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

```bash
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

```python
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`](CITATION.cff)).

## License

scROMA is released under the [GNU GPL v3](LICENSE).
