Skip to main content
CellCharter logo

A Python package for the identification, characterization and comparison of spatial clusters from spatial omics data.


Documentation • Examples • Paper • Preprint

Tests Documentation PyPI Downloads

Background

Spatial clustering (or spatial domain identification) determines cellular niches characterized by specific admixing of these populations. It assigns cells to clusters based on both their intrinsic features (e.g., protein or mRNA expression), and the features of neighboring cells in the tissue.

CellCharter is able to automatically identify spatial domains and offers a suite of approaches for cluster characterization and comparison.

Features

  • Identify niches for multiple samples: By combining the power of scVI and scArches, CellCharter can identify domains for multiple samples simultaneously, even with in presence of batch effects.
  • Scalability: CellCharter can handle large datasets with millions of cells and thousands of features. The possibility to run it on GPUs makes it even faster
  • Flexibility: CellCharter can be used with different types of spatial omics data, such as spatial transcriptomics, proteomics, epigenomics and multiomics data. The only difference is the method used for dimensionality reduction and batch effect removal.
    • Spatial transcriptomics: CellCharter has been tested on scVI with Zero-inflated negative binomial distribution.
      • Spatial proteomics: CellCharter has been tested on a version of scArches, modified to use Mean Squared Error loss instead of the default Negative Binomial loss.
      • Spatial epigenomics: CellCharter has been tested on scVI with Poisson distribution.
      • Spatial multiomics: it's possible to use multi-omics models such as MultiVI, or use the concatenation of the results from the different models.
  • Best candidates for the number of domains: CellCharter offers a method to find multiple best candidates for the number of domains, based on the stability of a certain number of domains across multiple runs.
  • Domain characterization: CellCharter provides a set of tools to characterize and compare the spatial domains, such as domain proportion, cell type enrichment, (differential) neighborhood enrichment, and domain shape characterization.

Since CellCharter 0.3.0, we moved the implementation of the Gaussian Mixture Model (GMM) from PyCave, not maintained anymore, to TorchGMM, a fork of PyCave maintained by the CSOgroup. This change allows us to have a more stable and maintained implementation of GMM that is compatible with the most recent versions of PyTorch.

Getting started

Please refer to the documentation. In particular, the

Installation

  1. Create a conda or pyenv environment
  2. Install Python >= 3.10,<3.13 and PyTorch >= 1.12.0. If you are planning to use a GPU, make sure to download and install the correct version of PyTorch first from here.
  3. Install the library used for dimensionality reduction and batch effect removal according to the data type you are planning to analyze:
    • scVI for spatial transcriptomics and/or epigenomics data such as 10x Visium and Xenium, Nanostring CosMx, Vizgen MERSCOPE, Stereo-seq, DBiT-seq, MERFISH and seqFISH data.
      • A modified version of scArches's TRVAE model for spatial proteomics data such as Akoya CODEX, Lunaphore COMET, CyCIF, IMC and MIBI-TOF data.
  4. Install CellCharter using pip:
pip install cellcharter

We report here an example of an installation aimed at analyzing spatial transcriptomics data (and thus installing scvi-tools). This example is based on a Linux CentOS 7 system with an NVIDIA A100 GPU. It will install Pytorch for GPU by default.

conda create -n cellcharter-env -c conda-forge python=3.12
conda activate cellcharter-env
pip install scvi-tools
pip install cellcharter

Note: a different system may require different commands to install PyTorch and JAX. Refer to their respective documentation for more details.

Contribution

If you found a bug or you want to propose a new feature, please use the issue tracker.

Metadata

Release files for cellcharter 0.3.9

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

Source distribution (sdist)

Source distribution for cellcharter 0.3.9
File Size Uploaded Provenance Actions
cellcharter-0.3.9.tar.gz 49.2 kB With provenance Details for cellcharter-0.3.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cellcharter 0.3.9
File Interpreter ABI Platform Actions
cellcharter-0.3.9-py3-none-any.whl Python 3 none any Details for cellcharter-0.3.9-py3-none-any.whl

Total release size: 102.1 kB

Release files / cellcharter-0.3.9.tar.gz

Download URL cellcharter-0.3.9.tar.gz
Size 49.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3f7f06aa9ae9027ab22dd2842cc9c0448098d06ea13c6104e6965f77f1cdc2fd
BLAKE2b-256 checksum
How to use checksums
0ec8296e4dc8dd22cb75e890dfedab0315013ece2240b88fa748b2b34d64b309
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 5, 2026.

Transparency log

Release files / cellcharter-0.3.9-py3-none-any.whl

Download URL cellcharter-0.3.9-py3-none-any.whl
Size 53.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6707011c5a24a99b54b6eb2d8b6e94fa73297372f5dfc6b89687cff0dc2488c8
BLAKE2b-256 checksum
How to use checksums
c23a28ba7032abb2e827b085f448602a2141b76ef52903a7a36c7ec8d8e09aae
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 5, 2026.

Transparency log

Security for cellcharter 0.3.9

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 cellcharter-0.3.9.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 5, 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