scATrans

scATrans is a Python toolkit for single-cell differential analysis. It is primarily designed for datasets that contain spliced/unspliced (or mature/nascent) RNA layers. In this setting it computes a composite active transcription score that integrates differential expression with reference-based excess unspliced RNA to rank genes.

It also supports conventional differential expression workflows (no velocity data required) using scanpy, PyDESeq2 pseudobulk, linear mixed models, or optional Memento. Functional enrichment (ORA, GSEA, GO, KEGG) uses bundled gene sets with consistent universe handling, and a set of visualization functions is provided.

Note: The spliced/unspliced (nascent-transcription) scoring is still experimental and under active validation — it is not yet recommended for production use on spliced/unspliced applications. The features that do not rely on the spliced/unspliced layers — differential expression, functional enrichment, and plotting — are stable and ready to use.

📚 Full documentation, tutorials, and the complete API reference are on Read the Docs.

Installation

# From PyPI
pip install scatrans

# Or from Bioconda
conda install -c conda-forge -c bioconda scatrans

# Optional extras (PyPI): advanced (scVelo) mode, gene features, pseudobulk DE (PyDESeq2), Memento, GSEA
pip install "scatrans[advanced,gene_features,pseudobulk,memento,gsea]"

See Installation for extras, source installs, and logging setup.

When developing from a git checkout, install the editable tree you are editing (pip install -e . from that checkout). A stale editable install pointing at another path can make import scatrans load an older copy.

Quickstart

import scatrans as scat

# One-liner pipeline: score → filter → GO enrichment
result = scat.run_default_pipeline(
    adata,
    groupby="condition",
    target_group="Disease",
    reference_group="Control",
    sample_col="sample",   # optional; auto-selects pseudobulk when >=3 replicates/group
    organism="mouse",
)
print(result["candidates"].head())
print(result["enrichment"].head())

See the Quickstart for a complete end-to-end walkthrough, the Tutorials for fully worked, real-data notebooks (with and without RNA-velocity layers), and the User Guide for DE backends, enrichment, plotting, and advanced options.

Before reporting results in a paper

active_score is a composite heuristic rank, not a p-value or FDR on its own. See Statistical Guidance for what each output column means, safe vs. unsafe uses, and a reporting checklist before you cite scATrans results in a manuscript or supplement. Domain conventions (upregulation-oriented scoring, residual vs DE, cutoff names, GSEA ranks, within-run λ scale) are spelled out in Domain Assumptions (also on Read the Docs after the next docs deploy).

License

Software (Python source) is licensed under Apache License 2.0. Bundled gene-set data (GO, KEGG) carries its own licensing terms — see License before commercial use.

Author

Zhao Li (李钊)
Email: leelieber@gmail.com