scXpand: Pan-cancer Detection of T-cell Clonal Expansion
Detect T-cell clonal expansion from single-cell RNA sequencing data without paired TCR sequencing
Preprint • Documentation • Installation • Quick Start • Usage Guide • Citation
A framework for predicting T-cell clonal expansion from single-cell RNA sequencing data.
Manuscript in preparation - detailed methodology and benchmarks coming soon.
View full documentation for comprehensive guides and API reference.
Features
- Multiple Model Architectures:
- Autoencoder-based: Encoder-decoder with reconstruction and classification heads
- MLP: Multi-layer perceptron
- LightGBM: Gradient boosted decision trees
- Linear Models: Logistic regression and support vector machines
- Scalable Processing: Handles millions of cells with memory-efficient data streaming from disk during training
- Automated Hyperparameter Optimization: Built-in Optuna integration for model tuning
Installation
For detailed installation instructions, please refer to our Installation Guide.
Published Version Install
CUDA version (NVIDIA GPU):
With pip:
pip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128
With uv:
uv pip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128 --index-strategy unsafe-best-match
CPU/Apple Silicon/Other GPUs:
With pip:
pip install --upgrade scxpand
With uv:
uv pip install --upgrade scxpand
Development Setup (Install from Source)
See the Installation Guide
Quick Start
import scxpand
# Make sure that "your_data.h5ad" includes only T cells for the results to be meaningful
# Ensure that "your_data.var_names" are provided as Ensembl IDs (as the pre-trained models were trained using this gene representation)
# Please refer to our documentation for more information
# List available pre-trained models
scxpand.list_pretrained_models()
# Run inference with automatic model download
results = scxpand.run_inference(
model_name="pan_cancer_autoencoder", # default model
data_path="your_data.h5ad"
)
# Access predictions
predictions = results.predictions
if results.has_metrics:
print(f"AUROC: {results.get_auroc():.3f}")
See our Tutorial Notebook for a complete example with data preprocessing, T-cell filtering, gene ID conversion, and model application using a real breast cancer dataset.
Documentation
Setup & Getting Started:
- Installation Guide - Setup for local development of scXpand
- User Guide - Quick start and comprehensive workflow guide
- Data Format - Input data requirements and specifications
Using Pre-trained Models:
- Model Inference - Run predictions on new data with pre-trained models
Training Your Own Models:
- Model Training - Train models with CLI and programmatic API
- Hyperparameter Optimization - Automated model tuning with Optuna
Understanding Results:
- Model Architectures - Detailed architecture descriptions and configurations
- Evaluation Metrics - Performance assessment and interpretation
- Output Format - Understanding model outputs and results
📖 Full Documentation - Complete guides, API reference, and interactive tutorials
License
This project is licensed under the MIT License – see the LICENSE file for details.
Citation
If you use scXpand in your research, please cite:
Shorer, O., Amit, R., and Yizhak, K. (2025). scXpand: Pan-cancer detection of T-cell clonal expansion from single-cell RNA sequencing without paired single-cell TCR sequencing. Preprint at bioRxiv, https://doi.org/10.1101/2025.09.14.676069.
BibTeX
@article{shorer2025scxpand,
title={scXpand: Pan-cancer detection of T-cell clonal expansion from single-cell RNA sequencing without paired single-cell TCR sequencing},
author={Shorer, Ofir and Amit, Ron and Yizhak, Keren},
year={2025},
journal={bioRxiv},
doi={https://doi.org/10.1101/2025.09.14.676069}
}
This project was created in favor of the scientific community worldwide, with a special dedication to the cancer research community.
We hope you'll find this repository helpful, and we warmly welcome any requests or suggestions - please don't hesitate to reach out!
2 maintainers
Metadata
2 maintainers
Release files for scxpand 0.4.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| scxpand-0.4.6.tar.gz | 7.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| scxpand-0.4.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.1 MB
Release files / scxpand-0.4.6.tar.gz
| Download URL | scxpand-0.4.6.tar.gz |
|---|---|
| Size | 7.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b7990c40343b2a6c37d174522bf6adfed19c46e834fa4b5ae58b3de78973cbe
|
|
BLAKE2b-256 checksum How to use checksums |
6c1aa466cb26a9c4004799168ed9c49bb3b0743a83ea7f2465909820ae5ed8df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / scxpand-0.4.6-py3-none-any.whl
| Download URL | scxpand-0.4.6-py3-none-any.whl |
|---|---|
| Size | 141.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeed6b8cb5628dec58e1f3c03528e03e27ec7d11aea91ae30df71617c6cffb8f
|
|
BLAKE2b-256 checksum How to use checksums |
26c69c062113fc54cdebc7cd84483032d67906779c2e6d18ebc65b9e87d0adbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
