Tangram

Tangram is a Python package built on PyTorch and scanpy designed for mapping single-cell (or single-nucleus) gene expression data onto spatial gene expression data.

To use Tangram effectively, your datasets should meet the following criteria:

• Biological Context: The single-cell dataset and the spatial dataset should be collected from the same anatomical region or tissue type (ideally from a biological replicate).
• Gene Overlap: The datasets must share a set of genes.

Tangram performs spatial alignment by fitting gene expression on these shared genes.

The tangram.mapping_optimizer module provides classes to optimize the mapping between different data representations (e.g., cell types or gene sets) using optimization techniques. It primarily exposes two classes for this purpose:

• Mapper: A standard mapper for finding optimal alignments or mappings.
• MapperConstrained: A mapper that allows for constraints to be applied during the optimization process, ensuring that certain mapping rules or boundaries are respected.

The tangram.mapping_utils module provides utility functions for mapping cells to a spatial reference and processing AnnData objects for downstream analysis.

Key functions include:

• map_cells_to_space: Maps cells to a spatial reference.
• adata_to_cluster_expression: Converts an AnnData object into cluster-level expression data.
• pp_adatas: Performs preprocessing on multiple AnnData objects.

Tangram finds a mapping matrix $M$ (shape: voxels-by-cells) by maximizing the similarity between the projected single-cell gene expression and the observed spatial gene expression.

Specifically, it maximizes the cosine similarity between the single-cell matrix $S$ (cell-by-training-genes) and the spatial matrix $G$ (voxels-by-genes). The element $M_{ij}$ signifies the probability of cell $i$ being located in voxel $j$.

Whether you need cell segmentation depends on your specific goal:

• For Mapping: You do not need to segment cells in your histology for mapping on spatial transcriptomics data (such as Visium or Slide-seq).
• For Deconvolution: You do need cell segmentation if you intend to deconvolve the data (i.e., deterministically assigning a single cell profile to each cell within a spatial voxel).

Tangram performs cell-type mapping by finding a mapping matrix $M$ (shape: voxels-by-cells) that minimizes a loss function. The goal is to ensure that the gene expression of the mapped single cells is as similar as possible to the spatial data $G$ using cosine similarity.

To instantiate the process, Tangram uses a Mapper object with two primary inputs:

• _S_: A single cell matrix with shape cell-by-gene. The number of genes must match the training genes.
• _G_: A spatial data matrix with shape voxels-by-genes. A single voxel can contain multiple cells.

The optimization seeks to minimize the loss between the reconstructed spatial expression and the observed spatial expression, where the mapping $M$ represents the probability of cell $i$ being in spot $j$.

To enable faster training and reduce memory consumption, you can perform mapping at the cell cluster level instead of individual cells.

1. Map: Call tg.map_cells_to_space with mode='clusters' and provide a cluster_label. The cluster_label must be a column existing in ad_sc.obs.
2. Project: When calling tg.project_genes, you must pass the same cluster_label used during the mapping step.

import tangram as tg

# Map at the cluster level
ad_map = tg.map_cells_to_space(
    ad_sc, 
    ad_sp,         
    mode='clusters',
    cluster_label='subclass_label'
)

# Project gene expression using the same cluster label
ad_ge = tg.project_genes(
    ad_map, 
    ad_sc,
    cluster_label='subclass_label'
)

To reduce memory consumption and speed up training, you can perform mapping at the cell cluster level. This requires providing a cluster_label that exists in ad_sc.obs.

When projecting genes after cluster-level mapping, you must pass the same cluster_label to tg.project_genes.

# Mapping at cluster level
ad_map = tg.map_cells_to_space(
    ad_sc, 
    ad_sp,         
    mode='clusters',
    cluster_label='subclass_label'
)

# Projecting genes with cluster label
ad_ge = tg.project_genes(
    ad_map, 
    ad_sc,
    cluster_label='subclass_label'
)

When selecting a list of training genes for mapping, consider the following strategies:

1. Marker Gene Approach: Use the top 1,000 unique marker genes, stratified across different cell types.
2. Whole Transcriptome: Map using the entire transcriptome.

Best Practices: Ensure your training genes contain high-quality signals. Avoid sets where most genes are prone to dropouts or were obtained with low-quality RNA probes, as this will decrease mapping accuracy.