scATrans

scATrans answers a simple follow-up after differential expression (DE): among the genes that changed, which look transcription-driven and which look stabilization-driven? It uses the nascent (unspliced) residual on top of a normal DE step—something total-count fold change alone cannot sort out.

Pathway- or program-level summaries (gene_sets=) are usually more useful than single-gene labels. Without spliced/unspliced layers, the package still runs ordinary DE, enrichment, and plots.

Docs: Read the Docs.

What you need

• Python 3.9+ (tested 3.9–3.12)
• An AnnData object with a condition column in .obs
• For mechanism analysis: spliced/unspliced (or mature/nascent) layers
• Nothing yet? scat.datasets.load_toy() ships a synthetic example — see First run.

Install

pip install scatrans
# or: conda install -c conda-forge -c bioconda scatrans

Optional extras (PyDESeq2, GSEA, scVelo, …): installation guide.

First run

No data on hand yet? This runs standalone, with no download, against a bundled synthetic example — good for checking your install works before touching real data:

import scatrans as scat

adata = scat.datasets.load_toy()  # synthetic, spliced/unspliced included

result = scat.partition_de_by_mechanism(
    adata,
    groupby="condition",
    target_group="Disease",
    reference_group="Control",
    organism="mouse",  # or "human"
    de="builtin",
    # sample_col="sample",   # set this when you have biological replicates
    # gene_sets=my_pathways, # optional pathway / program table
    # induction_matched=True,
)
print(result.regime)           # data-quality check on unspliced capture
print(result.selected.head())  # DE genes + soft mechanism labels
print(result.summary())
# Absolute program placement (optional):
# scat.program_mechanism_permutation_calibrated(adata, gene_sets, de=frozen_de, ...)

Swap in your own AnnData once that works end to end. Don't have spliced/unspliced (or mature/nascent) layers yet? See Preparing spliced/unspliced data for velocyto / kb-python / STARsolo / alevin-fry commands.

That is the recommended entry point. Next:

1. Quickstart
2. Tutorials
3. FAQ if something looks off

Status

0.10.x (Beta). Import as import scatrans as scat and stick to names in scatrans.__all__, scat.pl, and scat.qc. Details: API stability.

Citation

Please cite the preprint:

Li, Z., James, A. W. & Li, S. scATrans: annotating single-cell differential expression as transcription- or stabilization-weighted using unspliced RNA. bioRxiv (2026). doi:10.64898/2026.08.03.740741

For the software itself, cite the Zenodo DOI above. For analyses tied to package version 0.10.9, use scatrans==0.10.9. See CITATION.cff.

License

Software: Apache License 2.0. Bundled GO/KEGG data may carry separate terms—see the license page before commercial redistribution.

Author

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