Metadata-Version: 2.4
Name: scatrans
Version: 0.10.3
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)

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.

**📚 Full documentation, tutorials, and the complete API reference are on
[Read the Docs](https://scatrans.readthedocs.io/en/latest/).**

## Installation

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

```python
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](https://scatrans.readthedocs.io/en/latest/quickstart.html)
for a complete end-to-end walkthrough, the
[Tutorials](https://scatrans.readthedocs.io/en/latest/tutorials/index.html)
for fully worked, real-data notebooks (with and without RNA-velocity
layers), and the
[User Guide](https://scatrans.readthedocs.io/en/latest/user_guide/index.html)
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](https://scatrans.readthedocs.io/en/latest/statistical_guidance.html)
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](docs/domain_assumptions.md)
(also on Read the Docs after the next docs deploy).

## License

Software (Python source) is licensed under [Apache License 2.0](LICENSE).
Bundled gene-set data (GO, KEGG) carries its own licensing terms — see
[License](https://scatrans.readthedocs.io/en/latest/license.html) before
commercial use.

## Author

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