Infer cell-cell communication in spatial transcriptomics data using collective optimal transport.
Infer cell-cell communication from spatial transcriptomics data using collective optimal transport (COT). The method models ligand-receptor interactions as optimal transport problems with spatial distance constraints.
Usage
spatial_communication(
seurat_obj,
df_ligrec,
database_name = "commot",
assay = NULL,
slot = "data",
spatial_coords = NULL,
dis_thr = 500,
cost_scale = NULL,
heteromeric = TRUE,
heteromeric_delimiter = "_",
heteromeric_rule = c("min", "ave"),
cot_eps_p = 0.1,
cot_rho = 10,
cot_eps_mu = NULL,
cot_eps_nu = NULL,
cot_strategy = c("pairwise", "collective", "sender", "receiver"),
cot_weights = c(0.25, 0.25, 0.25, 0.25),
cot_nitermax = 10000L,
cot_stopthr = 1e-08,
pathway_sum = TRUE,
total_sum = TRUE,
n_workers = 1L,
verbose = TRUE
)Arguments
- seurat_obj
Seurat object containing spatial transcriptomics data.
- df_ligrec
Data frame of ligand-receptor pairs with columns:
ligand,receptor,pathway, and optionallysignaling_type. Obtain usingligand_receptor_databaseandfilter_lr_database.- database_name
Character string for naming stored results.
- assay
Assay to use for expression data (default: DefaultAssay).
- slot
Expression slot or layer to use (default: "data").
- spatial_coords
Spatial coordinates: NULL (auto-detect), character (reduction name), or matrix (n_cells x 2).
- dis_thr
Distance threshold for communication. Cell pairs beyond this distance have zero transport (default: 500).
- cost_scale
Scaling factor for cost normalization (default: 1/dis_thr).
- heteromeric
Logical, whether ligand/receptor can be multi-subunit complexes with subunits separated by delimiter (default: TRUE).
- heteromeric_delimiter
Character separating subunits (default: "_").
- heteromeric_rule
Aggregation rule for complex expression: "min" (default) uses minimum subunit expression, "ave" uses average.
- cot_eps_p
Entropy regularization coefficient (default: 0.1).
- cot_rho
Penalty coefficient for unmatched mass (default: 10).
- cot_eps_mu
Entropy regularization for source marginal (default: eps_p).
- cot_eps_nu
Entropy regularization for target marginal (default: eps_p).
- cot_strategy
COT aggregation strategy:
- "collective"
Joint optimization (most consistent)
- "sender"
Optimize per sender signal
- "receiver"
Optimize per receiver signal
- "pairwise"
Independent pair optimization (fastest)
- cot_weights
Weights for combining strategies (default: equal).
- cot_nitermax
Maximum Sinkhorn iterations (default: 10000).
- cot_stopthr
Convergence threshold (default: 1e-8).
- pathway_sum
Logical, compute pathway-level aggregates (default: TRUE).
- total_sum
Logical, compute total communication (default: TRUE).
- n_workers
Number of parallel workers (default: 1).
- verbose
Logical, print progress messages (default: TRUE).
Value
Seurat object with COMMOTR results stored in
seurat_obj@misc$commotr[[database_name]]. Access results using
get_communication_results.
Details
The method solves the unbalanced optimal transport problem: $$\min_P \langle C, P \rangle + \varepsilon \cdot \text{KL}(P | a \otimes b) + \rho \cdot (\text{KL}(P\mathbf{1} | a) + \text{KL}(P^T\mathbf{1} | b))$$
where \(C\) is the cost matrix (spatial distance), \(a\) and \(b\) are the source (ligand) and target (receptor) distributions, \(\varepsilon\) is the entropy regularization, and \(\rho\) is the penalty for unmatched mass.
References
Cang, Z., Zhao, Y., et al. Screening cell-cell communication in spatial transcriptomics via collective optimal transport. Nature Methods 20, 218-228 (2023).
Examples
if (FALSE) { # \dontrun{
# Load ligand-receptor database
df_lr <- ligand_receptor_database("CellChat", "mouse")
df_lr <- filter_lr_database(df_lr, seurat_obj)
# Infer spatial communication
seurat_obj <- spatial_communication(
seurat_obj,
df_ligrec = df_lr,
database_name = "CellChat",
dis_thr = 500,
n_workers = 4
)
# Access results
results <- get_communication_results(seurat_obj, "CellChat")
} # }