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!

Metadata

Release files for scxpand-cuda 0.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scxpand-cuda 0.4.6
File	Size	Uploaded
scxpand_cuda-0.4.6.tar.gz	7.0 MB	Oct 2, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for scxpand-cuda 0.4.6
File	Interpreter	ABI	Platform	Reset
scxpand_cuda-0.4.6-py3-none-any.whl 141.3 kB Oct 2, 2025	Python 3	none	any	Details

Total release size: 7.1 MB

Release files / scxpand_cuda-0.4.6.tar.gz

Download URL	scxpand_cuda-0.4.6.tar.gz
Size	7.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`46e49f0ba2279475e7c23770b66331b6cd5f744d1b6584931885f9344b4d0990`
BLAKE2b-256 checksum How to use checksums	`051700ad6e5128ce951f651b8f8a374d8f1aeec14aaa55a7deea5f01dabb0e3e`
Upload date	Oct 2, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Release files / scxpand_cuda-0.4.6-py3-none-any.whl

Download URL	scxpand_cuda-0.4.6-py3-none-any.whl
Size	141.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e9e3188722c04fc7f84d83bf05eec2aef7ed82a28e5e9522a949e824909a2298`
BLAKE2b-256 checksum How to use checksums	`ffe6d7b36214b225333841bdeaf0d5160cfc2aaa15beb5f702690c1629ec9211`
Upload date	Oct 2, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`