Metadata-Version: 2.4
Name: scatrans
Version: 0.10.10
Summary: Single-cell Active Transcription Analysis
Author-email: "Zhao Li (李钊)" <leelieber@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/leelieber2025/scATrans
Project-URL: Documentation, https://scatrans.readthedocs.io
Project-URL: Changelog, https://scatrans.readthedocs.io/en/latest/changelog.html
Keywords: single-cell,RNA-seq,unspliced,nascent RNA,active transcription,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scanpy>=1.9
Requires-Dist: anndata>=0.8
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: pyarrow>=10.0
Requires-Dist: scipy>=1.7
Requires-Dist: scikit-learn>=1.0
Requires-Dist: joblib>=1.2
Requires-Dist: statsmodels>=0.13
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.12
Requires-Dist: adjustText>=0.7
Requires-Dist: importlib_resources>=5.0; python_version < "3.10"
Provides-Extra: advanced
Requires-Dist: scvelo>=0.3.0; extra == "advanced"
Provides-Extra: pseudobulk
Requires-Dist: pydeseq2>=0.4.0; extra == "pseudobulk"
Provides-Extra: gene-features
Requires-Dist: gtfparse>=1.3.0; extra == "gene-features"
Provides-Extra: memento
Requires-Dist: memento-de<0.3.0,>=0.1.0; extra == "memento"
Provides-Extra: gsea
Requires-Dist: gseapy>=1.1; extra == "gsea"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pre-commit>=3.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# scATrans

[![PyPI version](https://img.shields.io/pypi/v/scatrans.svg)](https://pypi.org/project/scatrans/)
[![PyPI downloads](https://img.shields.io/pepy/dt/scatrans.svg)](https://pepy.tech/project/scatrans)
[![Bioconda](https://img.shields.io/conda/vn/bioconda/scatrans.svg)](https://anaconda.org/bioconda/scatrans)
[![Conda downloads](https://img.shields.io/conda/dn/bioconda/scatrans.svg)](https://anaconda.org/bioconda/scatrans)
[![Python versions](https://img.shields.io/pypi/pyversions/scatrans.svg)](https://pypi.org/project/scatrans/)
[![Documentation Status](https://readthedocs.org/projects/scatrans/badge/?version=latest)](https://scatrans.readthedocs.io/en/latest/?badge=latest)
[![CI](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml/badge.svg)](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21365873.svg)](https://doi.org/10.5281/zenodo.21365873)

**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.

| Step | What it does |
|------|----------------|
| DE | Chooses which genes make the list |
| Mechanism | Labels those genes (transcription vs. stabilization) |
| Detection (optional) | Extra nascent-activity scores; does not rewrite mechanism labels |

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](https://scatrans.readthedocs.io/en/latest/).

## 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](#first-run).

## Install

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

Optional extras (PyDESeq2, GSEA, scVelo, …):
[installation guide](https://scatrans.readthedocs.io/en/latest/installation.html).

## 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:

```python
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](https://scatrans.readthedocs.io/en/latest/tutorials/t_prepare_spliced_unspliced.html)
for velocyto / kb-python / STARsolo / alevin-fry commands.

That is the recommended entry point. Next:

1. [Quickstart](https://scatrans.readthedocs.io/en/latest/quickstart.html)
2. [Tutorials](https://scatrans.readthedocs.io/en/latest/tutorials/index.html)
3. [FAQ](https://scatrans.readthedocs.io/en/latest/faq.html) 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](https://scatrans.readthedocs.io/en/latest/api_stability.html).

## 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](LICENSE). Bundled GO/KEGG data may carry separate
terms—see the
[license page](https://scatrans.readthedocs.io/en/latest/license.html) before
commercial redistribution.

## Author

**Zhao Li (李钊)**  
Email: [leelieber@gmail.com](mailto:leelieber@gmail.com)
