Tangram

Tangram#

Note

This model is deprecated starting v1.5.

Tangram [Biancalani et al., 2021] (Python class Tangram) maps single-cell RNA-seq data to spatial data, permitting deconvolution of cell types in spatial data like Visium.

This is a reimplementation of Tangram, which can originally be found here.

The advantages of Tangram are:

  • It maps single-cell transcriptomes onto spatial observations with a directly interpretable mapping matrix.

  • It can project cell annotations, such as cell types, from single-cell data to spatial data.

  • It can project gene expression from the single-cell reference into spatial coordinates.

  • The scvi-tools implementation supports Tangram’s "cells" and "constrained" modes.

The limitations of Tangram include:

  • The scvi-tools model page is deprecated starting v1.5.

  • It requires matched genes between the single-cell and spatial modalities used for training.

  • Training is not mini-batched in the current implementation, so memory use depends on the number of single-cell observations and spatial observations.

  • Tangram is an optimization-based mapping model, not a generative model with posterior sampling.

Overview#

Tangram learns a matrix \(M\) with shape (\(n_{sc} \times n_{sp}\)), in which each row sums to 1. Thus, this matrix can be viewed as a map from single cells to the spatial observations.

Note

Starting scVI-Tools v1.5 this model is part of scVIVA-Tools, and no longer being maintained here.

Preliminaries#

Tangram is registered with setup_mudata(), not setup_anndata. The input is a MuData object containing a single-cell modality and a spatial modality. The two modalities used for training must contain the same genes in the same order.

The modalities argument tells Tangram which MuData modality contains each registered field. A typical setup registers:

  • sc_layer, the single-cell expression matrix used for mapping,

  • sp_layer, the spatial expression matrix used as the target, and

  • density_prior_key, an optional spatial observation column containing a density prior.

If a density prior is supplied, it must sum to 1. The tutorial computes a density prior from estimated cell counts in spatial observations.

Mapping Objective#

The mapping matrix \(M\) is parameterized by unconstrained trainable weights and converted to a row-stochastic matrix with a softmax. The predicted spatial expression matrix is:

\begin{align} \hat{X}_{sp} = M^\top X_{sc}, \end{align}

where \(X_{sc}\) is the single-cell expression matrix and \(\hat{X}_{sp}\) is the spatial expression predicted from mapped single cells.

Tangram optimizes a loss that rewards agreement between measured spatial expression and the predicted spatial expression. The default expression term uses gene-wise cosine similarity, and an optional spatial-observation-wise cosine term can also be enabled. If a density prior is registered, the loss includes a KL-divergence term between the predicted spatial density and the supplied prior.

In constrained mode, Tangram also learns a cell filter and requires target_count. The loss then includes a count term that encourages the selected number of cells to match target_count, plus a filter regularizer.

Tasks#

Here we provide an overview of common tasks. Please see Tangram for the full API reference.

Mapping Matrix#

After training, get_mapper_matrix() returns the mapping matrix with shape (n_obs_sc, n_obs_sp):

>>> mapper = model.get_mapper_matrix()

Each row contains a probability distribution over spatial observations for one single-cell observation.

Projection of Cell Annotations#

project_cell_annotations() uses the mapping matrix to project categorical single-cell labels, such as cell types, onto spatial observations:

>>> adata_sp.obsm["tangram_ct_pred"] = model.project_cell_annotations(
...     adata_sc, adata_sp, mapper, adata_sc.obs["cell_type"]
... )

The returned DataFrame has spatial observations as rows and label categories as columns.

Projection of Genes#

project_genes() multiplies the mapping matrix by the single-cell expression matrix and returns an AnnData object containing projected gene expression in spatial coordinates.