Skip to main content

CITEgeist

GitHub stars License Issues Python Version CI Code Quality

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 via use_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

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 is CITEgeist (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 to rna_refined) runs on CPU. Only method="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-cu12 from the NVIDIA index, or use a pre-built RAPIDS container). The default needs a raw_counts GEX 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

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)

Source distribution for citegeist 3.0.0
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)

Table of built distributions (wheels) for citegeist 3.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page