This vignette outlines Frequently Asked Questions (FAQ) when applying
CellChat to spatially resolved transcriptomics data, particularly on
how to set the spatial.factors for different types
of spatial transcriptomics data.
When inferring spatially-proximal cell-cell communication from spatially resolved transcriptomic data, user also should provide spatial coordinates/locations of spot/cell centroids. In addition, to filter out cell-cell communication beyond the maximum diffusion range of molecules (e.g., ~250μm), CellChat needs to compute the cell centroid-to-centroid distance in the unit of micrometers. Therefore, for spatial technologies that only provide spatial coordinates in pixels, CellChat converts spatial coordinates from pixels to micrometers by requiring users to input the conversion factor.
To infer spatially proximal cell-cell communication, in addition to the gene expression data matrix, CellChat requires additional three user inputs:
(1) meta (User assigned cell labels and
samples labels): a data frame (rows are cells with rownames)
consisting of cell information, which will be used for defining cell
groups. A column named samples should be provided for
spatial transcriptomics analysis, which is useful for analyzing
cell-cell communication by aggregating multiple samples/replicates. Of
note, for comparison analysis across different conditions, users still
need to create a CellChat object seperately for each condition.
(2) coordinates (Spatial coordinates of
spots/cells): a data frame in which each row gives the spatial
coordinates/locations of each cell/spot centroid.
(3) spatial.factors (Spatial factors of
spatial distance): a data frame containing two distance factors
ratio and tol, which is dependent on spatial
transcriptomics technologies (and specific datasets) and detailed as
follows:
ratio: the conversion factor when converting spatial
coordinates from Pixels or other units to Micrometers (i.e.,Microns).
For example, setting ratio = 0.18 indicates that 1 pixel
equals 0.18um in the coordinates.tol: the tolerance factor to increase the robustness
when comparing the center-to-center distance against the
interaction.range. This can be the half value of cell/spot
size in the unit of um. If the cell/spot size is not known, we provide a
function computeCellDistance to compute the cell
center-to-center distance. tol can be the the half value of
the minimum center-to-center distance. Of note, CellChat does not need
an accurate tolerance factor, which is used for determining whether
considering the cell-pair as spatially proximal if their distance is
greater than interaction.range but smaller than
“interaction.range + tol”.When inferring contact-dependent or juxtacrine signaling by setting
contact.dependent = TRUE in computeCommunProb,
and using L-R pairs from Cell-Cell Contact signaling
classified in CellChatDB$interaction$annotation, CellChat
requires another one user input:
contact.range: a value giving the
interaction range (Unit: microns) to restrict the contact-dependent
signaling. For spatial transcriptomics in a single-cell resolution,
contact.range is approximately equal to the estimated cell
diameter (i.e., the cell center-to-center distance), which means that
contact-dependent or juxtacrine signaling can only happens when the two
cells are contact to each other. Typically,
contact.range = 10, which is a typical human cell size.
However, for low-resolution spatial data such as 10X visium, it should
be the cell center-to-center distance (i.e.,
contact.range = 100 for 10X visium data). The function
computeCellDistance can compute the center-to-center
distance.Instead of providing contact.range, users may
alternatively provide a value of contact.knn.k, in order to
restrict the contact-dependent signaling within the k-nearest neighbors
(knn). Please check the documentation of computeCommunProb
for more details via help(computeCommunProb).
Below we provides suggestions on how to set the
spatial.factors for different types of spatial
transcriptomics data, including 10X Visium, Slide-seq, CosMx,
Stereo-seq, and seqFISH/merFISH/STARmap.
First, the spatial coordinates of spots from the full (NOT high/low)
resolution image should be used. For 10X Visium, this information is in
tissue_positions.csv. Given a Seurat object
seu of the spatial transcriptomics data, and spatial
coordinates can be obtained by
spatial.locs = GetTissueCoordinates(seu, scale = NULL, cols = c("imagerow", "imagecol"))Second, the conversion factor of converting spatial coordinates from
Pixels to Micrometers can be computed as the ratio of the theoretical
spot size (i.e., 65um) over the number of pixels that span the diameter
of a theoretical spot size in the full-resolution image (i.e.,
‘spot_diameter_fullres’ in pixels in the ‘scalefactors_json.json’ file).
Specifically, CellChat sets the spatial.factors as
follows:
scalefactors = jsonlite::fromJSON(txt = file.path("./tutorial/spatial_imaging_data_visium-brain", 'scalefactors_json.json'))
spot.size = 65 # the theoretical spot size (um) in 10X Visium
conversion.factor = spot.size/scalefactors$spot_diameter_fullres
spatial.factors = data.frame(ratio = conversion.factor, tol = spot.size/2)
d.spatial <- computeCellDistance(coordinates = spatial.locs, ratio = spatial.factors$ratio, tol = spatial.factors$tol)
min(d.spatial[d.spatial!=0]) # this value should approximately equal 100um for 10X Visium dataFinally, users can create a new CellChat object by taking spatial coordinates and spatial.factors as inputs:
cellchat <- createCellChat(object = data.input, meta = meta, group.by = "labels",
datatype = "spatial", coordinates = spatial.locs, spatial.factors = spatial.factors)For Slide-seq data, the spatial coordinates are in pixels and the
conversion factor of converting spatial coordinates from Pixels to
Micrometers is 0.73. The beads used in the current protocol have a
diameter of 10um. Thus, we directly set the spatial.factors
as follows:
conversion.factor = 0.73; spot.size = 10
spatial.factors = data.frame(ratio = conversion.factor, tol = spot.size/2)For CosMx data, the spatial coordinates are in pixels and the
conversion factor of converting spatial coordinates from Pixels to
Micrometers is 0.18. Because CosMx does not include the uniform cell
size like 10X Visium and Slide-seq, users can compute the minimum cell
centroid-to-centroid distance via computeCellDistance and
use its half value as the tolerance factor. Of note, CellChat does not
need an accurate tolerance factor, which is used for determining whether
considering the cell-pair as spatially proximal if their distance is
greater than interaction.range but smaller than
“interaction.range + tol”.
Thus, we set the spatial.factors as follows:
conversion.factor = 0.18
d = computeCellDistance(spatial.locs)
spot.size = min(d)*conversion.factor # converting the distance in Pixels to Micrometers
spatial.factors = data.frame(ratio = conversion.factor, tol = spot.size/2)For Stereo-seq data, please check the the post https://github.com/jinworks/CellChat/issues/6
For single-cell resolution spatial technologies like seqFISH/merFISH/STARmap data, the spatial coordinates are already in micrometers and thus the conversion factor is 1. The spot.size can be the typical human cell size (i.e., 10um).
conversion.factor = 1
spot.size = 10 # use the typical human cell size
spatial.factors = data.frame(ratio = conversion.factor, tol = spot.size/2)If there are only a few number of L-R pairs from the gene panel of the spatial dataset that can be found in the CellChat database, users can modify the step on the identification of over-expressed genes without performing DE. This can be done as follows
cellchat <- identifyOverExpressedGenes(cellchat, do.DE = FALSE, min.cells = 10)Please check the key steps of applying CellChat to multiple spatial transcriptomics datasets for detailed descriptions.
For comparison analysis of multiple spatial transcriptomics datasets across different biological conditions (e.g., health vs. diseased), users still need to create a CellChat object seperately for each condition. Please check the key steps of applying CellChat to multiple non-spatial transcriptomics datasets for detailed descriptions.
The CellChat version used in this vignette:
packageVersion("CellChat")## [1] '2.1.2'