Metadata-Version: 2.4
Name: scpdac
Version: 0.1.0
Summary: Mapping single cell data into PDAC atlases
Project-URL: Documentation, https://scPDAC.readthedocs.io/
Project-URL: Homepage, https://github.com/MDLDan/scPDAC
Project-URL: Source, https://github.com/MDLDan/scPDAC
Author: Daniele Lucarelli
Maintainer-email: Daniele Lucarelli <daniele.lucarelli@tum.de>
License: MIT License
        
        Copyright (c) 2025, Daniele Lucarelli
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: scarches
Requires-Dist: session-info2
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: scikit-learn; extra == 'dev'
Requires-Dist: scvi-tools; extra == 'dev'
Requires-Dist: twine>=4.0.2; extra == 'dev'
Provides-Extra: doc
Requires-Dist: docutils!=0.18.*,!=0.19.*,>=0.8; extra == 'doc'
Requires-Dist: ipykernel; extra == 'doc'
Requires-Dist: ipython; extra == 'doc'
Requires-Dist: myst-nb>=1.1; extra == 'doc'
Requires-Dist: pandas; extra == 'doc'
Requires-Dist: setuptools; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-book-theme>=1; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-tabs; extra == 'doc'
Requires-Dist: sphinx>=8.1; extra == 'doc'
Requires-Dist: sphinxcontrib-bibtex>=1; extra == 'doc'
Requires-Dist: sphinxext-opengraph; extra == 'doc'
Provides-Extra: eval
Requires-Dist: matplotlib; extra == 'eval'
Requires-Dist: seaborn; extra == 'eval'
Provides-Extra: test
Requires-Dist: coverage>=7.10; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

# scPDAC

[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]

[badge-tests]: https://img.shields.io/github/actions/workflow/status/MDLDan/scPDAC/test.yaml?branch=main
[badge-docs]: https://img.shields.io/readthedocs/scPDAC

**scPDAC** maps and annotates single-cell RNA-seq data against pancreatic ductal
adenocarcinoma (PDAC) reference atlases. It ships pretrained models for **human**
and **mouse** and exposes two complementary workflows:

- 🧬 **Atlas mapping** — project a query dataset into a reference SCANVI latent
  space, either with scArches surgery (`scpdac.tl.extend_atlas`, tolerates new
  batches and returns an expanded atlas) or a fast embed-only label transfer
  (`scpdac.tl.embed_and_predict`) — all while retaining your original metadata.
- 🏷️ **Hierarchical annotation** — label cells with a 3-model hierarchical MLP
  classifier (`scpdac.tl.predict_labels`) that first splits *Malignant* vs
  *Non-Malignant* and then assigns fine-grained cell types with a dedicated
  sub-classifier for each branch.

Both paths align your genes to the model's panel automatically and write the
predictions straight back into your `AnnData`.

## Getting started

Please refer to the [documentation][]. The [atlas mapping][] and
[hierarchical classifier][] tutorials walk through both workflows end-to-end,
the [performance][] page reports held-out benchmarks and known limitations, and
the [API documentation][] lists every public function.

## Installation

You need to have Python 3.11 or newer installed on your system.
If you don't have Python installed, we recommend installing [uv][].


1) Install the latest release of `scPDAC` from [PyPI][]:

```bash
pip install scPDAC
```

## Release notes

See the [changelog][].

## Contact

For questions and help requests, or to report a bug, please open an issue.

## Citation

If you use scPDAC in your research, please cite:

> Lucarelli D, Parikh S, Jiménez S, *et al.* Cross-species single-cell atlases
> chart progression, therapy-driven remodelling and immune evasion in pancreatic
> cancer. *bioRxiv* (2026). doi:[10.64898/2026.03.19.712924](https://doi.org/10.64898/2026.03.19.712924)

```bibtex
@article{Lucarelli2026,
  author    = {Lucarelli, Daniele and Parikh, Shrey and Jim{\'e}nez, Sara and others},
  title     = {Cross-species single-cell atlases chart progression, therapy-driven remodelling and immune evasion in pancreatic cancer},
  journal   = {bioRxiv},
  year      = {2026},
  doi       = {10.64898/2026.03.19.712924},
  publisher = {Cold Spring Harbor Laboratory},
  url       = {https://www.biorxiv.org/content/10.1101/2026.03.19.712924},
}
```

[uv]: https://github.com/astral-sh/uv
[issue tracker]: https://github.com/MDLDan/scPDAC/issues
[tests]: https://github.com/MDLDan/scPDAC/actions/workflows/test.yaml
[documentation]: https://scPDAC.readthedocs.io
[changelog]: https://scPDAC.readthedocs.io/en/latest/changelog.html
[api documentation]: https://scPDAC.readthedocs.io/en/latest/api.html
[atlas mapping]: https://scPDAC.readthedocs.io/en/latest/notebooks/mapping.html
[hierarchical classifier]: https://scPDAC.readthedocs.io/en/latest/notebooks/classifier.html
[performance]: https://scPDAC.readthedocs.io/en/latest/performance.html
[pypi]: https://pypi.org/project/scPDAC
