CellRelay

CellRelay is an R package for identifying multicellular ligand-receptor-ligand-receptor (LRLR) relay motifs from single-cell and spatial transcriptomic data.

Most cell-cell communication workflows infer pairwise sender-receiver ligand-receptor interactions. CellRelay extends this idea to coordinated three-cell cascades:

---

---

The downstream ligand L2 is linked to upstream signaling through a ligand-target prior, so each LRLR motif represents a biologically connected candidate relay rather than an arbitrary pair of ligand-receptor interactions.

Installation

install.packages("remotes")
remotes::install_github("jinyangye119/CellRelay")

CellRelay expects a working Seurat installation:

install.packages("Seurat")

Main features

• Calculate average gene expression by cell type.
• Generate LRLR relay motif tables from a Seurat object.
• Score LRLR relay activity.
• Perform empirical permutation tests:
  • cell-label permutation for expression-driven activity;
  • role-specificity permutation for CellA-CellB-CellC enrichment.
• Summarize cell relay programs such as Tumor -> CAF -> Macrophage.
• Summarize LR relay motifs such as MDK-LRP1 -> C3-ITGAX+ITGB2.
• Identify feed-forward relay candidates with direct CellA-CellC signals.
• Plot top cell relays and top LR relay motifs.

Quick start

library(CellRelay)
library(Seurat)

db <- load_cellrelay_database()
lr_network <- db$lr_network
ligand_ligand <- db$ligand_ligand

# `obj` is a normalized Seurat object with cell-type labels in obj$Cell.type.
avg_expr <- calculate_average_expression(
  obj,
  cell_type_label = "Cell.type",
  assay = "RNA",
  slot = "data"
)

lrlr_table <- generate_lrlr_table(
  seurat_obj = obj,
  lr_network = lr_network,
  ligand_ligand = ligand_ligand,
  condition_name = "sample",
  pct_cut = 0.1,
  use_pct = TRUE,
  use_deg = FALSE
)

lrlr_activity <- calculate_lrlr_activity(
  lrlr_table,
  avg_expr = avg_expr
)

perm <- LRLR_permute_fast(
  result_table = lrlr_table,
  seurat_obj = obj,
  cell_type_label = "Cell.type",
  n_perm = 100,
  workers = 4
)

cell_relays <- calculate_cell_relay(perm)
lr_motifs <- calculate_lr_relay_motifs(perm)

plot_cell_relay(cell_relays, top_n = 15)
plot_lr_relay_motifs(lr_motifs, top_n = 15)

For exploratory runs, use a small number of permutations. For publication analysis, increase n_perm and set a fixed seed.

Feed-forward relays

CellRelay also supports feed-forward relay analysis, where the linear CellA-CellB-CellC cascade co-exists with direct CellA-CellC signaling.

ffd_candidates <- classify_ffd_relays(lrlr_table)

ffd_perm <- LRLR_permute_FFD_fast(
  result_table = ffd_candidates,
  seurat_obj = obj,
  cell_type_label = "Cell.type",
  n_perm = 100
)

summarize_ffd_relays(ffd_perm)

Vignette

A reproducible PBMC example is included in:

vignette("pbmc-cellrelay", package = "CellRelay")

The vignette downloads the public 10x PBMC dataset, preprocesses it with Seurat, generates a CellRelay LRLR table, runs a small demonstration permutation analysis, and plots top cell relays and LR relay motifs.

Input requirements

CellRelay requires:

1. A normalized Seurat object.
2. A metadata column containing cell type or cluster labels, by default Cell.type.
3. A ligand-receptor table with columns ligand and receptors.
4. A ligand-target prior represented as a named list where each name is an upstream ligand and each value is a vector of downstream ligand targets.

Bundled prior files are available through:

db <- load_cellrelay_database()

Key functions

Function	Purpose
calculate_average_expression()	Average gene expression by cell type
generate_lrlr_table()	Generate CellA-CellB-CellC LRLR candidates
calculate_lrlr_activity()	Add LRLR activity scores
LRLR_permute_fast()	Linear relay permutation testing
calculate_cell_relay()	Rank cell-type relay programs
calculate_lr_relay_motifs()	Rank L1-R1-L2-R2 relay motifs
classify_ffd_relays()	Annotate direct CellA-CellC feed-forward candidates
LRLR_permute_FFD_fast()	Feed-forward relay permutation testing
plot_cell_relay()	Plot top cell relays
plot_lr_relay_motifs()	Plot top LR relay motifs

Citation

If you use CellRelay, please cite the CellRelay manuscript and the underlying ligand-receptor resources used in your analysis.