DOCSEARCHbyAlgolia
Submit Docs

cell2location

repository·master·Indexed 19 days ago

https://github.com/bayraktarlab/cell2location

A principled Bayesian model for mapping fine-grained cell types in spatial transcriptomics data by integrating single-cell RNA-seq reference signatures. It features a hierarchy of Python classes supporting PyMC3, PyTorch, and Pyro frameworks for spatial location estimation and regression tasks. The library includes tools for computing cell type abundance, analyzing cellular compartments via sklearn NMF, performing Archetypal Analysis, and visualizing spatial abundance.

Tokens
10.8K
Snippets
34
Records
59
Agent score
65%

What's inside cell2location

  1. Use cell2location infrastructure classes for Pyro and scvi-tools

    master

    cell2location utilizes a specialized infrastructure built on top of Pyro and scvi-tools to handle probabilistic modeling. The core functionality is divided into mixin classes for model behavior and module classes for model initialization and execution.

    Base Mixin Classes

    Found in cell2location.models.base._pyro_mixin, these classes provide shared functionality across different model types:

    • AutoGuide setup: Automates the configuration of guides for variational inference.
    • Posterior quantile computation: Methods for calculating quantiles from the posterior distribution.
    • Plotting & export: Utilities for visualizing model results and exporting data.

    scvi-tools Module Classes

    These classes manage the lifecycle of the models, including initialization of the model and the guide. The primary base class is PyroBaseModuleClass.

  2. Configure cell2location hyperparameters: N_cells_per_location and detection_alpha

    master

    The cell2location model requires two critical user-provided hyperparameters:

    1. N_cells_per_location: Controls the expected number of cells per spatial location.
    2. detection_alpha: Controls the sensitivity to technical variability in RNA detection.

    Selecting detection_alpha: Many datasets (particularly human datasets) exhibit within-slide variability in RNA detection sensitivity. You should choose based on the observed technical variability:

    • Use detection_alpha=200 for low within-slide technical variability.
    • Use detection_alpha=20 for high within-slide technical variability.

  3. How cell2location models work

    master

    cell2location is implemented using pyro and scvi-tools to support several distinct modeling tasks:

    Spatial Mapping and Reference Estimation

    1. Spatial mapping of cell types: Estimates cell abundance by decomposing spatial data into reference expression signatures of cell types. This uses the LocationModelLinearDependentWMultiExperimentLocationBackgroundNormLevelGeneAlphaPyroModel.
    2. Reference expression signature estimation: Estimates signatures from scRNA data while accounting for variable sequencing depth between batches (e.g., 10X reaction), additive background (contaminating RNA), and multiplicative platform effects between scRNA technologies.
    3. Nanostring WTA mapping: A specific model for mapping to Nanostring WTA data using LocationModelWTA. (Note: For a more versatile version, see the SpaceJam repository).
    4. Simplified models: Accessible via cell2location.models.simplified, these are versions of the spatial mapping model that lack certain features of the full model.

    Downstream Analysis

    Two models are provided for analyzing cell abundance estimates, located in cell2location.models.downstream:

    1. CoLocatedGroupsSklearnNMF: Identifies groups of cell types with similar locations using Non-negative Matrix Factorization (NMF), acting as a wrapper around sklearn NMF.
    2. ArchetypalAnalysis: Identifies smoothly varying and mutually exclusive tissue zones using Archetypal Analysis.

  4. Understand the underlying Pyro and scvi-tools modules

    master

    For advanced users or those extending the model, cell2location utilizes Pyro and scvi-tools modules to define and initialize the probabilistic models.

    • RegressionBackgroundDetectionTechPyroModel: This is the Pyro Module class used to define the generative model using the Pyro probabilistic programming language.
    • RegressionBackgroundDetectionTechPyroModel (scvi-tools Module): This class is used for initializing the model and the guide within the scvi-tools framework, facilitating training and inference.

  5. Select simplified PyMC3 model architectures

    master

    If the main model is too computationally intensive or if your data does not require certain statistical assumptions, you can use simplified model architectures:

    • LocationModelLinearDependentWMultiExperiment: A version without normalization.
    • LocationModelHierarchicalWMultiExperiment: Uses hierarchical priors but does not perform prior factorization of w_sf.
    • LocationModelMultiExperiment: No prior factorization of w_sf.
    • LocationModelLinearDependentWMultiExperimentNoMg: Removes the gene-specific platform effect m_g.
    • LocationModelLinearDependentWMultiExperimentNoSegLs: Removes the additive background RNA component.

  6. Understand the cell2location model inheritance structure

    master

    The cell2location models are implemented as a hierarchy of Python classes to facilitate method reuse across different probabilistic programming frameworks (PyMC3, PyTorch, and Pyro).

    Framework-specific Base Classes

    • BaseModel: Provides core methods required for PyMC3, PyTorch, and Pyro implementations.
    • Pymc3Model: Contains methods specific to PyMC3-based models.
    • TorchModel: Contains methods specific to PyTorch-based models.
    • PyroModel: Contains methods specific to Pyro-based models.

    PyMC3 Model Hierarchy

    PyMC3 models are used for spatial location estimation. The hierarchy is as follows:

    • Pymc3LocModel: Models where gene weights are fixed (2nd dimension) and weights for observations are estimated (1st dimension).
      • LocationModelLinearDependentW: The main cell2location model; accounts for similarity in cell type locations.
      • LocationModelLinearDependentWMultiExperiment: An extension of the main model for joint modeling of multiple spatial experiments.
      • LocationModel: A simplified model that treats cell type locations as independent.
    • CoLocatedCombination_sklearnNMF: Uses NMF to analyze cell type abundance estimated by cell2location.
    • ArchetypalAnalysis: Uses Archetypal Analysis to analyze cell type abundance estimated by cell2location.

    PyTorch Model Hierarchy

    Torch models are used for regression tasks:

    • RegressionTorchModel: Models where observation weights are fixed (1st dimension) and gene weights are estimated (2nd dimension).
      • RegressionGeneBackgroundCoverageTorch: Specialized regression for background coverage.
      • RegressionGeneBackgroundCoverageGeneTechnologyTorch: (In development) Specialized regression for gene technology effects.

    Pyro Model Hierarchy

    Pyro models provide a translation of location models to the Pyro framework:

    • PyroLocModel: Models where gene weights are fixed (2nd dimension) and weights for observations are estimated (1st dimension).
      • LocationModelLinearDependentWPyro: The Pyro translation of the main cell2location model (accounts for location similarity).
      • LocationModelPyro: The Pyro translation of the simplified independent location model.

  7. Install cell2location manually

    master

    If you prefer to build the environment manually, follow these steps.

    Warning: Do not install pymc3 and theano via conda, as they may not use the system CUDA drivers. Instead, install them via pip after creating the conda environment.

    1. Create the conda environment with core dependencies:
    conda create -n cellpymc python=3.7 numpy pandas jupyter leidenalg python-igraph scanpy \
louvain hyperopt loompy cmake nose tornado dill ipython bbknn seaborn matplotlib request \
mkl-service pygpu --channel bioconda --channel conda-forge
    1. Activate the environment and install pymc3, theano, and other pip-specific packages:
    conda activate cellpymc
pip install plotnine "arviz==0.10.0" "pymc3>=3.8,<3.10" torch pyro-ppl
    1. Install the cell2location package itself:
    conda activate cellpymc
pip install git+https://github.com/BayraktarLab/cell2location.git
    # Step 1: Create conda env
conda create -n cellpymc python=3.7 numpy pandas jupyter leidenalg python-igraph scanpy \
louvain hyperopt loompy cmake nose tornado dill ipython bbknn seaborn matplotlib request \
mkl-service pygpu --channel bioconda --channel conda-forge

# Step 2: Install pip dependencies
conda activate cellpymc
pip install plotnine "arviz==0.10.0" "pymc3>=3.8,<3.10" torch pyro-ppl

# Step 3: Install cell2location
pip install git+https://github.com/BayraktarLab/cell2location.git

  8. Prevent Python from using user site packages

    master

    To ensure a fully isolated conda environment and avoid package version mismatches (often caused by the python user site), set the PYTHONNOUSERSITE environment variable. You can add this to your ~/.bashrc or run it in your current terminal session.

    export PYTHONNOUSERSITE="someletters"

  10. Prevent package version mismatches using PYTHONNOUSERSITE

    master

    To ensure a fully isolated conda environment and avoid issues where Python uses packages from your user site instead of the conda environment, set the PYTHONNOUSERSITE environment variable. This should be done before creating the environment and before every new terminal session where you activate the environment.

    Note: The value assigned to PYTHONNOUSERSITE can be any arbitrary string.

    export PYTHONNOUSERSITE="literallyanyletters"

  11. Install cell2location via Conda

    master

    It is recommended to use a separate conda environment for cell2location. To install the package along with tutorial dependencies, create a new environment and use pip install cell2location[tutorials].

    To use the environment within a Jupyter Notebook, you must register it as a kernel.

    # Create and activate environment
conda create -y -n cell2loc_env python=3.10
conda activate cell2loc_env

# Install package with tutorials
pip install cell2location[tutorials]

# Register as Jupyter kernel
python -m ipykernel install --user --name=cell2loc_env --display-name='Environment (cell2loc_env)'