Metadata-Version: 2.4
Name: scatrans
Version: 0.10.7
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/)
[![Bioconda](https://img.shields.io/conda/vn/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** is a Python package for mechanism-aware single-cell differential
analysis. A standard differential expression (DE) step defines which genes
changed; scATrans partitions those genes into *transcription-driven* versus
*stabilization-driven* classes using the nascent (unspliced) RNA residual—a
distinction that total-count fold change alone cannot resolve.

| Component | Role |
|-----------|------|
| DE | Gene-list membership |
| Mechanism annotation | Residual-based transcription vs. stabilization labels |
| Detection (optional) | `add_nascent_score=True` adds active-transcription scores; does not drive mechanism labels |

The primary workflow requires spliced and unspliced layers (or mature and
nascent layers, e.g. from kb-python) and is most informative at the pathway or
program level. The package also supports conventional DE without nascent layers
(scanpy, PyDESeq2 pseudobulk, linear mixed models, optional Memento), enrichment
(ORA, GSEA, GO, KEGG), and plotting.

Full documentation: [Read the Docs](https://scatrans.readthedocs.io/en/latest/).

## Requirements

- Python 3.10+
- AnnData object with a condition column in `.obs`
- For mechanism analysis: `spliced`/`unspliced` or `mature`/`nascent` layers

## Installation

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

Optional extras (scVelo, gene-feature CLI, PyDESeq2, Memento, GSEA) and
development installs:
[installation guide](https://scatrans.readthedocs.io/en/latest/installation.html).

## Quickstart

```python
import scatrans as scat

result = scat.partition_de_by_mechanism(
    adata,  # AnnData with spliced/unspliced or mature/nascent layers
    groupby="condition",
    target_group="Disease",
    reference_group="Control",
    organism="mouse",
    de="builtin",  # method name, kwargs dict, DataFrame, or callable
    # add_nascent_score=True,  # optional detection columns
    gene_sets=my_pathways,  # optional program-level table
)
result.regime    # reliability pre-flight (global unspliced fraction)
result.selected  # DE-selected genes with mechanism annotation
result.programs  # program-level table when gene_sets is provided
```

Further reading:

- [Quickstart](https://scatrans.readthedocs.io/en/latest/quickstart.html)
- [Tutorials](https://scatrans.readthedocs.io/en/latest/tutorials/index.html)
- [User Guide](https://scatrans.readthedocs.io/en/latest/user_guide/index.html)
- [FAQ](https://scatrans.readthedocs.io/en/latest/faq.html) (scope and limitations)
- [Statistical Guidance](https://scatrans.readthedocs.io/en/latest/statistical_guidance.html)

## Status

scATrans is **0.10.x (Beta)**. Prefer `import scatrans as scat` and names in
`scatrans.__all__`, `scat.pl`, and `scat.qc`. See
[API stability](https://scatrans.readthedocs.io/en/latest/api_stability.html).

## Citation

If you use scATrans in published work, cite the software via the Zenodo DOI
above and the manuscript when available. See `CITATION.cff`.

## License

Software: [Apache License 2.0](LICENSE). Bundled gene-set data (GO, KEGG) 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)
