<div align="center">
<img src="https://raw.githubusercontent.com/yizhak-lab-ccg/scXpand/main/docs/images/scXpand_logo_gray.png" alt="scXpand Logo" width="280"/>
<h1 style="margin: 10px 0 5px 0;">scXpand: Pan-cancer Detection of T-cell Clonal Expansion</h1>
<p style="margin: 0 0 25px 0; font-size: 0.95em; max-width: 800px; line-height: 1.4;">
Detect T-cell clonal expansion from single-cell RNA sequencing data without paired TCR sequencing
</p>
<p style="margin: 0;">
<a href="https://scxpand.readthedocs.io/en/stable/" style="margin: 0 8px;">Documentation</a> •
<a href="#installation" style="margin: 0 8px;">Installation</a> •
<a href="#quick-start" style="margin: 0 8px;">Quick Start</a> •
<a href="docs/usage_examples.rst" style="margin: 0 8px;">Examples</a> •
<a href="#citation" style="margin: 0 8px;">Citation</a>
</p>
</div>
<div style="width: 100vw; margin-left: calc(-50vw + 50%); margin-right: calc(-50vw + 50%); margin-top: 20px; margin-bottom: 40px; padding: 0 40px;">
<img src="https://raw.githubusercontent.com/yizhak-lab-ccg/scXpand/main/docs/images/scXpand_datasets.jpeg" alt="scXpand Datasets Overview" style="width: 100%; height: auto; display: block; margin: 0; padding: 0;"/>
</div>
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](https://scxpand.readthedocs.io/en/stable/)** 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
scXpand is available in two variants to match your hardware:
**If you have an NVIDIA GPU with CUDA support:**
With plain *pip* (add CUDA index):
```bash
pip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128
```
With **uv**:
```bash
uv pip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128 --index-strategy unsafe-best-match
```
**Otherwise (CPU, Apple Silicon, or non-CUDA GPUs):**
With plain *pip*:
```bash
pip install --upgrade scxpand
```
With **uv**:
```bash
uv pip install --upgrade scxpand
```
See the [full installation guide](https://scxpand.readthedocs.io/en/stable/installation.html) for detailed setup instructions.
## Quick Start
```python
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"
)
```
## Documentation
See our **[Tutorial Notebook](notebooks/scxpand_tutorial.ipynb)** for a complete example with data preprocessing, T-cell filtering, gene ID conversion, and model application using a real breast cancer dataset.
**Getting Started:**
- **[Development Guide](docs/installation.rst)** - Setup for local development of scXpand
- **[Usage Examples](docs/usage_examples.rst)** - Detailed tutorials and CLI examples
- **[Data Format](docs/data_format.rst)** - Input data requirements and specifications
**Model Training & Optimization:**
- **[Model Architectures](docs/model_architectures.rst)** - Detailed architecture descriptions and configurations
- **[Hyperparameter Optimization](docs/hyperparameter_optimization.rst)** - Automated model tuning with Optuna
- **[Data Pipeline](docs/data_pipeline.rst)** - Preprocessing and normalization details
**Analysis & Evaluation:**
- **[Evaluation Metrics](docs/evaluation_metrics.rst)** - Performance assessment and stratified analysis
- **[Output Format](docs/output_format.rst)** - Understanding model outputs and results
**[📖 Full Documentation](https://scxpand.readthedocs.io/en/stable/)** - Complete guides, API reference, and interactive tutorials
## License
This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
## Citation
If you use scXpand in your research, please cite:
```bibtex
@article{scxpand2025,
title={scXpand: Pan-cancer detection of T-cell clonal expansion from single-cell RNA sequencing without paired single-cell TCR sequencing},
author={[Your Name]},
journal={[Journal Name]},
year={2025},
doi={[DOI]}
}
```
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!
<p align="center">
<a href="https://mapmyvisitors.com/web/1bz9s">
<img src="https://mapmyvisitors.com/map.png?d=hwaNi7bepoJeL9CYnuB3WjMT-liNG4MvcmwecZk3aNA&cl=ffffff">
</a>
</p>
<p align="center">
<a href="#">
<img src="https://visitor-badge.laobi.icu/badge?page_id=yizhak-lab-ccg.scXpand&left_text=scXpand%20Visitors" alt="Visitors" />
</a>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "scxpand-cuda",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": "single-cell, RNA-seq, T-cell, clonal-expansion, machine-learning, bioinformatics, cuda, gpu",
"author": null,
"author_email": "Ron Amit <ronamit@ef.technion.ac.il>, Ofir Shorer <ofirshorer@campus.technion.ac.il>",
"download_url": "https://files.pythonhosted.org/packages/53/bd/1c307a26ec29abe1590378a8971f9ecb9d393a9257560f8048ac65e19834/scxpand_cuda-0.1.58.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/yizhak-lab-ccg/scXpand/main/docs/images/scXpand_logo_gray.png\" alt=\"scXpand Logo\" width=\"280\"/>\n\n <h1 style=\"margin: 10px 0 5px 0;\">scXpand: Pan-cancer Detection of T-cell Clonal Expansion</h1>\n\n <p style=\"margin: 0 0 25px 0; font-size: 0.95em; max-width: 800px; line-height: 1.4;\">\n Detect T-cell clonal expansion from single-cell RNA sequencing data without paired TCR sequencing\n </p>\n\n <p style=\"margin: 0;\">\n <a href=\"https://scxpand.readthedocs.io/en/stable/\" style=\"margin: 0 8px;\">Documentation</a> \u2022\n <a href=\"#installation\" style=\"margin: 0 8px;\">Installation</a> \u2022\n <a href=\"#quick-start\" style=\"margin: 0 8px;\">Quick Start</a> \u2022\n <a href=\"docs/usage_examples.rst\" style=\"margin: 0 8px;\">Examples</a> \u2022\n <a href=\"#citation\" style=\"margin: 0 8px;\">Citation</a>\n </p>\n</div>\n\n<div style=\"width: 100vw; margin-left: calc(-50vw + 50%); margin-right: calc(-50vw + 50%); margin-top: 20px; margin-bottom: 40px; padding: 0 40px;\">\n <img src=\"https://raw.githubusercontent.com/yizhak-lab-ccg/scXpand/main/docs/images/scXpand_datasets.jpeg\" alt=\"scXpand Datasets Overview\" style=\"width: 100%; height: auto; display: block; margin: 0; padding: 0;\"/>\n</div>\n\nA framework for predicting T-cell clonal expansion from single-cell RNA sequencing data.\n\n**Manuscript in preparation** - detailed methodology and benchmarks coming soon.\n\n**[View full documentation](https://scxpand.readthedocs.io/en/stable/)** for comprehensive guides and API reference.\n\n\n## Features\n\n- **Multiple Model Architectures**:\n - **Autoencoder-based**: Encoder-decoder with reconstruction and classification heads\n - **MLP**: Multi-layer perceptron\n - **LightGBM**: Gradient boosted decision trees\n - **Linear Models**: Logistic regression and support vector machines\n- **Scalable Processing**: Handles millions of cells with memory-efficient data streaming from disk during training\n- **Automated Hyperparameter Optimization**: Built-in Optuna integration for model tuning\n\n## Installation\n\nscXpand is available in two variants to match your hardware:\n\n**If you have an NVIDIA GPU with CUDA support:**\n\nWith plain *pip* (add CUDA index):\n\n```bash\npip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128\n```\n\nWith **uv**:\n\n```bash\nuv pip install --upgrade scxpand-cuda --extra-index-url https://download.pytorch.org/whl/cu128 --index-strategy unsafe-best-match\n```\n\n**Otherwise (CPU, Apple Silicon, or non-CUDA GPUs):**\n\nWith plain *pip*:\n\n```bash\npip install --upgrade scxpand\n```\n\nWith **uv**:\n```bash\nuv pip install --upgrade scxpand\n```\n\nSee the [full installation guide](https://scxpand.readthedocs.io/en/stable/installation.html) for detailed setup instructions.\n\n## Quick Start\n\n```python\nimport scxpand\n# Make sure that \"your_data.h5ad\" includes only T cells for the results to be meaningful\n# Ensure that \"your_data.var_names\" are provided as Ensembl IDs (as the pre-trained models were trained using this gene representation)\n# Please refer to our documentation for more information\n\n# List available pre-trained models\nscxpand.list_pretrained_models()\n\n# Run inference with automatic model download\nresults = scxpand.run_inference(\n model_name=\"pan_cancer_autoencoder\", # default model\n data_path=\"your_data.h5ad\"\n)\n```\n\n\n## Documentation\n\nSee our **[Tutorial Notebook](notebooks/scxpand_tutorial.ipynb)** for a complete example with data preprocessing, T-cell filtering, gene ID conversion, and model application using a real breast cancer dataset.\n\n\n**Getting Started:**\n- **[Development Guide](docs/installation.rst)** - Setup for local development of scXpand\n- **[Usage Examples](docs/usage_examples.rst)** - Detailed tutorials and CLI examples\n- **[Data Format](docs/data_format.rst)** - Input data requirements and specifications\n\n**Model Training & Optimization:**\n- **[Model Architectures](docs/model_architectures.rst)** - Detailed architecture descriptions and configurations\n- **[Hyperparameter Optimization](docs/hyperparameter_optimization.rst)** - Automated model tuning with Optuna\n- **[Data Pipeline](docs/data_pipeline.rst)** - Preprocessing and normalization details\n\n**Analysis & Evaluation:**\n- **[Evaluation Metrics](docs/evaluation_metrics.rst)** - Performance assessment and stratified analysis\n- **[Output Format](docs/output_format.rst)** - Understanding model outputs and results\n\n**[\ud83d\udcd6 Full Documentation](https://scxpand.readthedocs.io/en/stable/)** - Complete guides, API reference, and interactive tutorials\n\n## License\n\nThis project is licensed under the MIT License \u2013 see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use scXpand in your research, please cite:\n\n```bibtex\n@article{scxpand2025,\n title={scXpand: Pan-cancer detection of T-cell clonal expansion from single-cell RNA sequencing without paired single-cell TCR sequencing},\n author={[Your Name]},\n journal={[Journal Name]},\n year={2025},\n doi={[DOI]}\n}\n```\n\nThis project was created in favor of the scientific community worldwide, with a special dedication to the cancer research community.\nWe hope you\u2019ll find this repository helpful, and we warmly welcome any requests or suggestions - please don\u2019t hesitate to reach out!\n\n<p align=\"center\">\n <a href=\"https://mapmyvisitors.com/web/1bz9s\">\n <img src=\"https://mapmyvisitors.com/map.png?d=hwaNi7bepoJeL9CYnuB3WjMT-liNG4MvcmwecZk3aNA&cl=ffffff\">\n </a>\n</p>\n<p align=\"center\">\n <a href=\"#\">\n <img src=\"https://visitor-badge.laobi.icu/badge?page_id=yizhak-lab-ccg.scXpand&left_text=scXpand%20Visitors\" alt=\"Visitors\" />\n </a>\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "Pan-cancer detection of T-cell clonal expansion from single-cell RNA sequencing (CUDA-enabled)",
"version": "0.1.58",
"project_urls": {
"Documentation": "https://scxpand.readthedocs.io/en/stable/",
"Homepage": "https://github.com/yizhak-lab-ccg/scXpand",
"Issues": "https://github.com/yizhak-lab-ccg/scXpand/issues",
"Logo": "https://raw.githubusercontent.com/yizhak-lab-ccg/scXpand/main/docs/images/scXpand_logo_gray.png",
"Repository": "https://github.com/yizhak-lab-ccg/scXpand"
},
"split_keywords": [
"single-cell",
" rna-seq",
" t-cell",
" clonal-expansion",
" machine-learning",
" bioinformatics",
" cuda",
" gpu"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58932850d7fe13eed8ec199304a038e5e16ad95ad89e5b83ca1e0d6457eb87ab",
"md5": "7693a1d66ad8e6c815b02276b6611e48",
"sha256": "306b36bd961969c75d2b04c14dab93782515186840a9f8db4ecc87d089edb87f"
},
"downloads": -1,
"filename": "scxpand_cuda-0.1.58-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7693a1d66ad8e6c815b02276b6611e48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 138232,
"upload_time": "2025-09-13T17:46:14",
"upload_time_iso_8601": "2025-09-13T17:46:14.374827Z",
"url": "https://files.pythonhosted.org/packages/58/93/2850d7fe13eed8ec199304a038e5e16ad95ad89e5b83ca1e0d6457eb87ab/scxpand_cuda-0.1.58-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "53bd1c307a26ec29abe1590378a8971f9ecb9d393a9257560f8048ac65e19834",
"md5": "5f9b582dcc28d71569801dacfe4a24bd",
"sha256": "7841657000f7c72210e7d7163cee30b64b1fe34d4ab2b724e0d33d450560f84d"
},
"downloads": -1,
"filename": "scxpand_cuda-0.1.58.tar.gz",
"has_sig": false,
"md5_digest": "5f9b582dcc28d71569801dacfe4a24bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 126733,
"upload_time": "2025-09-13T17:46:15",
"upload_time_iso_8601": "2025-09-13T17:46:15.998801Z",
"url": "https://files.pythonhosted.org/packages/53/bd/1c307a26ec29abe1590378a8971f9ecb9d393a9257560f8048ac65e19834/scxpand_cuda-0.1.58.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 17:46:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yizhak-lab-ccg",
"github_project": "scXpand",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "scxpand-cuda"
}
JSON
