cellcharter

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

---

Documentation • Examples • Paper • Preprint

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 be 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 concatenativo of the results from the different models.
• Best candidates for 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, domain shape characterization.

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

Getting started

Please refer to the documentation. In particular, the

• API documentation.
• Tutorials

Installation

1. Create a conda or pyenv environment
2. Install Python >= 3.8 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 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 suggest using mamba to install the dependencies. Installing the latest version of the dependencies (in particular scvi-tools and spatialdata) may lead to dependency conflicts. However, this should not be a problem because CellCharter doesn't use any of the mismatching features.

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.

conda create -n cellcharter-env -c conda-forge python mamba
conda activate cellcharter-env
mamba install pytorch torchvision torchaudio pytorch-cuda=12.4 -c pytorch -c nvidia
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.