CITEgeist
Cellular Indexing of Transcriptomes and Epitopes for Guided Exploration of Intrinsic Spatial Trends
CITEgeist is a comprehensive computational framework for analyzing spatial multi-omic data, with a focus on integrating CITE-seq and spatial transcriptomics. Our toolkit enables researchers to uncover spatial patterns in cellular organization and gene expression, providing deeper insights into tissue architecture and function.
Key Features
- Reference-free cell-type deconvolution using same-slide CITE-seq antibody capture — no scRNA-seq reference required
- CPU cell-type proportion estimation (default: SPOTS marker share plus reference-free RNA refinement); GPU quadratic programming (cuOPT) available with
method="qp" - SACE per-cell gene expression deconvolution via single-pass Poisson-multinomial allocation
- Per-cell type assignment from spot proportions via StarDist nuclei segmentation. The default
is count-constrained Hungarian matching; the morphology-Bayesian posterior
(
morphology/nucleus_scores.py) is available viause_morphology=True - Spatial gene program discovery and cross-sample integration (Modules 4–5)
- Validated on dense tumor microenvironments including breast cancer and RCC clinical samples
Documentation
- Quick Start Guide
- Running on Real Visium Data (end-to-end tutorial)
- Benchmarking Methodology
- Example Scripts
Data Availability
| Dataset | Used for | Source |
|---|---|---|
| Visium + CITE-seq clinical-trial samples (this study) | Midkine / ESR1-D538G analyses; competitor-GEX validation | NCBI GEO GSE289326 |
| Wu et al. 2021 breast cancer scRNA-seq atlas | Reference for reference-based competitor methods; source cells for the simulation | NCBI GEO GSE176078 |
| Xenium Human Kidney Dataset (renal cell carcinoma) | Real-tissue benchmark | 10x Genomics, publicly available |
Reproducibility
Example end-to-end pipelines for each module are in examples/scripts.
See the end-to-end Visium tutorial to run CITEgeist on real data.
The curated analysis code behind the paper's reported numbers — with a map from each script to
the figure it produces — is in
examples/paper_analysis.
Reproducing the benchmarks
The code behind the paper's benchmark figures and tables is in Benchmarking/. Its README maps each figure and table to its scripts and lists the environment variables, data layout and data sources you need.
System Requirements
Minimum Requirements
- Python 3.10
- 16GB RAM
- Multi-core processor
- NVIDIA GPU with 8GB+ VRAM (optional; only needed for
method="qp", the cuOPT QP solver) - Linux, macOS, or Windows 10 with WSL2
Quick Installation
CITEgeist is published on PyPI:
pip install citegeist
Note — package name vs import name: The installed distribution is named
citegeist(lowercase), but the importable package isCITEgeist(capital C). After installation:import CITEgeist # bare import (lightweight) from CITEgeist import CitegeistModel # lazy re-export — heavy stack loaded on demand
GPU is optional: the default proportion method (
method="auto", which resolves torna_refined) runs on CPU. Onlymethod="qp"(the 2.0.0 behaviour) needs an NVIDIA GPU with CUDA and the cuOPT library. cuOPT is not available on PyPI — install it via NVIDIA RAPIDS or NGC (pip install cuopt-cu12from the NVIDIA index, or use a pre-built RAPIDS container). The default needs araw_countsGEX layer and per-spot nuclei counts.
To install from source instead:
git clone https://github.com/leeoesterreich/CITEgeist.git
cd CITEgeist
pip install -e .
For a development installation with test and lint dependencies:
pip install -e .[dev]
Development Setup
For Contributors
If you want to contribute to CITEgeist, follow these steps:
# Clone the repository
git clone https://github.com/leeoesterreich/CITEgeist.git
cd CITEgeist
# Create conda environment
conda env create -f CITEgeist_env.yml
conda activate CITEgeist_env
# Install in development mode with dev dependencies
pip install -e ".[dev]"
Code Quality Tools
We use several tools to maintain code quality:
- black: Code formatting (120 char line length)
- isort: Import sorting
- flake8: Linting
- mypy: Type checking
- pylint: Static code analysis
- pytest: Testing framework
Run quality checks before committing:
# Format code
black CITEgeist/
isort CITEgeist/
# Run linting
flake8 CITEgeist/
pylint CITEgeist/
# Run tests
pytest
CI enforcement (blocks sync to main): black, isort, flake8, pytest/coverage
Advisory (badge only, no merge gate): pylint, mypy
See CONTRIBUTING.md for detailed contribution guidelines.
License
This project is licensed under the BSD 3-Clause License - see the LICENSE file for details. BSD 3-Clause is a permissive license: you may use, modify, and redistribute the code, including in proprietary work, provided you retain the copyright notice and do not use the authors' names to endorse derived products.
Contact
- Lab Website: Lee/Oesterreich Laboratory
- Issues: GitHub Issues
- Email: Contact Us
Citation
If you use CITEgeist in your research, please cite our paper: (to be updated)
@article{ChangSchlegelCITEgeistCellularIndexing2025,
title = {{{CITEgeist}}: {{Cellular Indexing}} of {{Transcriptomes}} and {{Epitopes}} for {{Guided Exploration}} of {{Intrinsic Spatial Trends}}},
shorttitle = {{{CITEgeist}}},
author = {Chang, Alexander Chih-Chieh and Schlegel, Brent T. and Carleton, Neil and McAulife, Priscilla F. and Oesterreich, Steffi and Schwartz, Russell and Lee, Adrian V.},
date = {2025-02-17},
eprinttype = {bioRxiv},
eprintclass = {New Results},
pages = {2025.02.15.638331},
doi = {10.1101/2025.02.15.638331},
url = {https://www.biorxiv.org/content/10.1101/2025.02.15.638331v1},
urldate = {2025-02-17},
abstract = {Spatial transcriptomics provides insights into tissue architecture by linking gene expression with spatial localization. Current deconvolution methods rely heavily on single-cell RNA sequencing (scRNA-seq) references, which are costly and often unavailable, mainly if the tissue under evaluation is limited, such as in a core biopsy specimen. We present a novel tool, CITEgeist, that deconvolutes spatial transcriptomics data using antibody capture from the same slide as the reference, directly leveraging cell surface protein measurements from the same tissue section. This approach circumvents the limitations of scRNA-seq as a reference, offering a cost-effective and biologically grounded alternative. Our method employs mathematical optimization to estimate cell type proportions and gene expression profiles, incorporating sparsity constraints for robustness and interpretability. Benchmarks against state-of-the-art deconvolution methods show improved accuracy in cell type resolution, particularly in dense tumor microenvironments, while maintaining computational efficiency. This antibody-based tool advances spatial transcriptomics by providing a scalable, accurate, and reference-independent solution for deconvolution in complex tissues. We validate this tool by using a combined approach of simulated data and clinical samples by applying CITEgeist to translational pre-treatment and post-treatment ER+ breast tumors from an ongoing clinical trial, emphasizing the applicability and robustness of CITEgeist.},
}
Contributing
We welcome contributions! Please see our CONTRIBUTING.md for detailed guidelines on:
- Setting up your development environment
- Code quality standards
- Testing requirements
- Pull request process
Support
For support, please:
- Open an issue on our GitHub issue tracker
- Check existing issues and discussions
- Read our documentation and examples
Copyright (c) 2025 Lee/Oesterreich Lab
Metadata
Release files for citegeist 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| citegeist-3.0.0.tar.gz | 265.8 kB | With provenance | Details for citegeist-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| citegeist-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for citegeist-3.0.0-py3-none-any.whl |
Total release size: 567.4 kB
Release files / citegeist-3.0.0.tar.gz
| Download URL | citegeist-3.0.0.tar.gz |
|---|---|
| Size | 265.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
07f3abc32b9c9bcf255e38a910200c3fff78f28ebe8e1c1d8505fd14a4f2f9b4
|
|
BLAKE2b-256 checksum How to use checksums |
5b12951dfd2bf2f356efa5c5b7818048ea87d7e1e9852f8e50510705b2a4cd69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / citegeist-3.0.0-py3-none-any.whl
| Download URL | citegeist-3.0.0-py3-none-any.whl |
|---|---|
| Size | 301.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
332a5237babc228c6bb66835b8c959169b50abe7cf1e36be89d999c24e588666
|
|
BLAKE2b-256 checksum How to use checksums |
8d613809303e7682864741482b0ae8f17815e03c077eef8e6b0cf312a1e0b901
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for citegeist 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for citegeist-3.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.