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

• 📘 Quick Start Guide
• 📗 Algorithm Theory
• 📙 Visualization Gallery
• 📕 Full Tutorial

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

MIT © Zaoqu Liu

---

Developed by Zaoqu Liu
liuzaoqu@163.com