Metadata-Version: 2.4
Name: turep
Version: 0.1.0
Summary: Tumor-reactivity prediction for single-cell and spatial transcriptomics data.
Author-email: Wendao Liu <liuwd15@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/liuwd15/turep
Project-URL: Repository, https://github.com/liuwd15/turep
Project-URL: Documentation, https://github.com/liuwd15/turep/blob/main/README.md
Keywords: single-cell,bioinformatics,machine-learning,vae,focal-loss
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.12.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scvi-tools>=1.3.0
Requires-Dist: fadvi>=0.2.0
Requires-Dist: anndata>=0.8.0
Requires-Dist: lightning>=2.0.0
Requires-Dist: torchmetrics>=0.11.0
Requires-Dist: platformdirs>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Dynamic: license-file

# Turep

**Cross-cancer tumor-reactive CD8+ T cell prediction**

`turep` is a Python package for predicting tumor-reactive CD8+ T cells from
single-cell and spatial transcriptomics data across solid tumors.


## Installation

### From Pypi

```bash
pip install turep
```

### From source

```bash
cd turep
pip install -e .
```


## Usage

### scRNA-seq prediction (Turep-sc)

Use the hosted pre-trained model and run prediction directly on query data.

```python
from turep import load_model, predict_tr

# Load the hosted pre-trained turep model.
# The pretrained model will be downloaded during the first run
turep_model = load_model()

# adata_query is an AnnData input with a column "sample_id" indicating
# biological sample. It should be subsetted to include CD8+ T cells.
adata_query = ... 
adata_query = predict_tr(adata_query, turep_model, "sample_id")
head(adata_query.obs)
```

Predictions are written to ``adata_query.obs["label_pred"]`` and
``adata_query.obs["score_pred"]``.

If you have TCR clonotype information saved in a column of adata_query.obs,
The tumor-reactive probability of TCR clonotypes can be predicted based on Turep score prediction.

```python
from turep import get_top_clonotype

# Uses adata_query.obs["clone_id"] and adata_query.obs["score_pred"] by default
top_clonotypes = get_top_clonotype(adata_query, clonotype_key="clone_id", K=5, C=0.5)
print(top_clonotypes.head())
```

### Spatial transcriptomics prediction (Turep-st)

Factor disentanglement VAE models with focal loss that separate batch effects, biological labels, and residual variation.

```python
from turep import load_model, predict_tr_spatial

adata_ref = load_model().adata

# adata_query is an AnnData input with a column "sample_id" indicating
# biological sample. It should be subsetted to include CD8+ T cells.
adata_query = ... 
adata_query = predict_tr_spatial(adata_query, adata_ref, "sample_id")
head(adata_query.obs)
```

## Resources

The notebooks and scripts for reproducing and visualizing results in our manuscript are available at [turep_notebooks](https://github.com/liuwd15/turep_notebooks).

## Citation

If you use this package in your research, please cite our preprint: [Liu et al. bioRxiv. 2026](https://doi.org/10.64898/2026.04.21.719961).
