scATrans Documentation

scATrans Documentation#

What scATrans does#

Differential expression tells you which genes change. With nascent or unspliced layers, scATrans asks how those changes sit on a transcription-versus-stabilization axis.

Per-gene labels are exploratory.
Report mechanism at the program level when you can.
DE still defines the gene list.

No nascent layers? You can still run DE, enrichment, and plotting.

 spliced + unspliced AnnData
             │
             ▼
    ┌──────────────────┐
    │ 1. DE             │   selects the gene list (Wilcoxon / PyDESeq2 / …)
    │    (defines it)   │
    └──────────────────┘
             │  DE-selected genes only
             ▼
    ┌──────────────────┐
    │ 2. Mechanism      │   unspliced-excess residual →
    │    (annotates it) │   transcription- vs stabilization-driven (soft, per gene)
    └──────────────────┘
             │  optional: gene_sets={program: [genes]}
             ▼
    ┌──────────────────┐
    │ 3. Program table  │   pooled, induction-matched / permutation-calibrated
    │    (report here)  │   → the level to report, not single genes
    └──────────────────┘

Step 1 decides which genes; steps 2–3 decide how — never the reverse.

Where to go#

Goal	Page
Install and run a first analysis	Installation → Quickstart
Pick an API or program test	FAQ / Troubleshooting and the table below
Full workflow, enrichment, plots	User Guide · Tutorials
What each column means for a paper	Statistical Guidance and Reporting Checklist
Math and formal API	Method: Nascent residual and mechanism annotation · API Reference

A sensible path#

Install: pip install "scatrans[pseudobulk]" (add [gsea] if you need GSEA).
Follow Quickstart.
Work through a real notebook (Partition DE by mechanism — transcription vs stabilization or Partition by mechanism — GA vs Ctrl).
Enrich the DE gene list; keep mechanism claims at the program level when you can.

Default call#

No data yet? scat.datasets.load_toy() returns a synthetic AnnData with spliced/unspliced layers already in place, so the block below runs as-is, no download needed. Swap in your own AnnData once it works; if it lacks nascent layers, see Preparing spliced/unspliced data.

import scatrans as scat

adata = scat.datasets.load_toy()  # or your own AnnData

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 when you have biological replicates
    # gene_sets=my_pathways,
    # induction_matched=True,
)
print(result.regime)           # capture quality
print(result.selected.head())  # DE genes + mechanism labels
print(result.summary())        # cutoffs and counts used for this run

Which tool for which job#

Goal	Use
DE + mechanism (usual case)	`partition_de_by_mechanism`
DE / enrichment only (no velocity layers)	`differential_expression` + `run_enrichment`
Program vs genome-wide background	`gene_sets=` → `result.programs`
Program with induction controlled	`induction_matched=True`
Absolute program placement	`program_mechanism_permutation_calibrated`
Optional nascent detection score	`add_nascent_score=True` (does not set mechanism labels)
Enrichment	On `result.selected`, not on `mechanism_class` splits

Practical habits: define membership with DE, treat per-gene classes as soft, prefer programs for claims, and pass sample_col when you have replicates. See FAQ / Troubleshooting.

Note

scATrans is 0.10.x (Beta). Prefer import scatrans as scat and the public names in scatrans.__all__, scat.pl, and scat.qc. Details: API Stability.

Installation

pip, Bioconda, optional extras.

Installation

Quickstart

First run after install.

Quickstart

Tutorials

Worked notebooks (read online or re-run).

Tutorials

User Guide

Workflow, enrichment, plots, advanced options.

User Guide

FAQ

API choice and common errors.

FAQ / Troubleshooting

Statistical Guidance

What each column is for.

Statistical Guidance and Reporting Checklist

Method

Residual and calibration math.

Method: Nascent residual and mechanism annotation

API Reference

Functions and parameters.

API Reference

GitHub

Source and issues.

https://github.com/leelieber2025/scATrans