COMMOTR

📖 Documentation: https://zaoqu-liu.github.io/COMMOTR/

Overview

COMMOTR (Cell-cell cOMMunication via cOllective opTimal tRansport) is an R package for inferring spatially-resolved cell-cell communication in spatial transcriptomics data. The package implements collective optimal transport (COT) algorithms to model ligand-receptor interactions with explicit spatial distance constraints.

This package provides a native R implementation of the COMMOT algorithm, featuring:

🚀 High-performance C++ backend via RcppArmadillo
🔗 Native Seurat integration (v4/v5 compatible)
📊 Comprehensive visualization toolkit
💻 Full cross-platform compatibility

Methodology

COMMOTR formulates cell-cell communication as an unbalanced optimal transport problem:

$$\min_{P \geq 0} \langle C, P \rangle + \varepsilon \cdot \text{KL}(P | a \otimes b) + \rho \cdot \left( \text{KL}(P\mathbf{1} | a) + \text{KL}(P^\top\mathbf{1} | b) \right)$$

where:

$C$ is the spatial distance-based cost matrix
$a$ and $b$ are the ligand and receptor expression distributions
$\varepsilon$ is the entropy regularization parameter
$\rho$ is the penalty coefficient for unmatched mass (unbalanced transport)
$\text{KL}(\cdot | \cdot)$ denotes the Kullback-Leibler divergence

The optimization is solved efficiently using the Sinkhorn-Knopp algorithm with numerical stabilization via the log-sum-exp technique.

Installation

From R-universe (Recommended)

install.packages("COMMOTR", repos = "https://zaoqu-liu.r-universe.dev")

From GitHub

# install.packages("remotes")
remotes::install_github("Zaoqu-Liu/COMMOTR")

System Requirements

R (≥ 4.0.0)
C++ compiler with C++11 support
Dependencies: Rcpp, RcppArmadillo, Matrix, Seurat, ggplot2

Quick Start

library(COMMOTR)
library(Seurat)

# Load ligand-receptor database
df_lr <- ligand_receptor_database("CellChat", "mouse", "Secreted Signaling")
df_lr <- filter_lr_database(df_lr, seurat_obj, min_cell_pct = 0.05)

# Infer spatial communication
seurat_obj <- spatial_communication(
    seurat_obj,
    df_ligrec = df_lr,
    database_name = "CellChat",
    dis_thr = 500,           # Distance threshold (μm)
    cot_eps_p = 0.1,         # Entropy regularization
    cot_rho = 10             # Unbalanced penalty
)

# Compute communication direction (vector field)
seurat_obj <- communication_direction(
    seurat_obj,
    database_name = "CellChat",
    pathway_name = "TGFb"
)

# Cluster-level analysis with permutation testing
seurat_obj <- cluster_communication(
    seurat_obj,
    database_name = "CellChat",
    clustering = "seurat_clusters",
    pathway_name = "TGFb",
    n_permutations = 1000
)

Core Functions

Function	Description
`spatial_communication()`	Infer cell-cell communication via collective optimal transport
`communication_direction()`	Compute spatial vector fields of signaling directions
`cluster_communication()`	Aggregate to cluster-level with permutation testing
`ligand_receptor_database()`	Load curated ligand-receptor databases
`filter_lr_database()`	Filter LR pairs by expression criteria

Visualization

Function	Description
`plot_cell_communication()`	Spatial plot with vector field overlay
`plot_cluster_communication()`	Network diagram of cluster communication
`plot_communication_dotplot()`	Dot plot for pathway/LR pair comparison
`plot_communication_heatmap()`	Heatmap visualization
`plot_chord_diagram()`	Chord diagram via `circlize`

Built-in Databases

Database	Species	Interactions
CellChat	Mouse	2,019
CellChat	Human	1,939
CellChat	Zebrafish	2,774
CellPhoneDB v4.0	Mouse	1,410
CellPhoneDB v4.0	Human	1,680

Tutorials

Citation

If you use COMMOTR in your research, please cite the original COMMOT publication:

Cang, Z., Zhao, Y., Almet, A.A. et al. Screening cell–cell communication in spatial transcriptomics via collective optimal transport. Nature Methods 20, 218–228 (2023). https://doi.org/10.1038/s41592-022-01728-4

Related Resources

Original Python Implementation: COMMOT
CellChat Database: CellChat
CellPhoneDB: CellPhoneDB

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests on GitHub.

License

Developed by Zaoqu Liu
liuzaoqu@163.com