Title:	Population-Level Cell-Cell Communication Analysis Tools
Version:	0.1.0.1
Description:	Facilitates population-level analysis of ligand-receptor (LR) interactions using large-scale single-cell transcriptomic data. Identifies significant LR pairs and quantifies their interactions through correlation-based filtering and projection score computations. Designed for large-sample single-cell studies, the package employs statistical modeling, including linear regression, to investigate LR relationships between cell types. It provides a systematic framework for understanding cell-cell communication, uncovering regulatory interactions and signaling mechanisms. Offers tools for LR pair-level, sample-level, and differential interaction analyses, with comprehensive visualization support to aid biological interpretation. The methodology is described in a manuscript currently under review and will be referenced here once published or publicly available.
Depends:	R (≥ 4.1.0)
Imports:	Seurat (≥ 4.1.0), broom (≥ 1.0.0), dplyr (≥ 1.0.0), purrr (≥ 0.3.0), rlang, stringr (≥ 1.4.0), tibble (≥ 3.0.0), tidyr (≥ 1.0.0), tidyselect (≥ 1.1.0), Matrix (≥ 1.2-0), ggplot2 (≥ 3.3.0), ggpubr (≥ 0.6.0), pheatmap (≥ 1.0.12), RColorBrewer, reshape2 (≥ 1.4.1), scales (≥ 1.1.1), igraph (≥ 2.0.0), parallel, pbmcapply (≥ 1.5.0), grDevices
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.2.3
LazyData:	true
NeedsCompilation:	no
Packaged:	2025-04-25 09:12:42 UTC; gongz
Author:	Zheng Gong [aut, cre], Mengwei Li [aut, ctb]
Maintainer:	Zheng Gong <gongzheng131@hotmail.com>
Repository:	CRAN
Date/Publication:	2025-04-25 15:20:09 UTC

Boxplot Comparison of Ligand-Receptor Interaction Scores Across Groups

Description

Generates a boxplot comparing LR (ligand-receptor) interaction scores across sample groups. with optional significance testing (t-test or Wilcoxon).

Usage

boxplot_lr_group_comparison(
  lr_scores,
  metadata,
  ligand,
  receptor,
  sender,
  receiver,
  group_by,
  score = c("normalized", "raw"),
  test = TRUE,
  paired = FALSE,
  test_method = c("wilcox.test", "t.test"),
  colors = c("#5fa9d1", "#154778"),
  title = NULL
)

Arguments

Value

A list containing:

• plot - ggplot object of the boxplot

• df - data frame used for plotting

Examples

# Boxplot of LR Score by group
data(lr_scores_eg)
data(metadata_eg)
res <- boxplot_lr_group_comparison(
  lr_scores_eg, metadata_eg,
  ligand = "TAC4", receptor = "TACR1",
  sender = "Perivascular", receiver = "Cardiac",
  group_by = "IFN_type", score = "normalized"
)

print(res$plot)
head(res$df)

Plot Circular Ligand-Receptor Interaction Network

Description

Plots a circular ligand-receptor (LR) interaction network with curved directed edges. Nodes are arranged in a circle, and edge widths and colors represent interaction strengths.

Usage

circle_plot(
  filtered_lr,
  edge_width = c("count", "cor"),
  node_colors = NULL,
  show_self_interactions = TRUE,
  cutoff = 0
)

Arguments

Value

A recordedplot object representing the network plot.

Examples

# Plot Circular Cell-Cell Interaction Network
data(filtered_lr_eg)
p <- circle_plot(filtered_lr_eg, edge_width = "count", show_self_interactions = TRUE)
print(p)

Create Ligand-Receptor Interaction Dot Plot

Description

Generates a dot plot to visualize ligand-receptor (LR) interaction. Dot sizes are scaled by the correlation coefficient and dot colors represent -log10(adjust.p). The function supports plotting the top interactions per sender-receiver pair or user-specified ligand-receptor pairs.

Usage

dot_plot(
  filtered_lr,
  top_n = 5,
  axis = c("LR-SR", "SR-LR"),
  type_scale = c("size", "radius"),
  selected_LR = NULL
)

Arguments

Value

A ggplot object representing the dot plot.

Examples

# Plot LR Interaction Dot Plot
data(filtered_lr_eg)
p <- dot_plot(filtered_lr_eg, axis = "LR-SR", type_scale = "size")
print(p)

Dotplot of Ligand-Receptor Interaction Scores Against Continuous Group Variable

Description

Creates a dotplot (scatter plot) of LR interaction scores against a continuous variable with optional regression line.

Usage

dotplot_lr_continuous_group(
  lr_scores,
  metadata,
  ligand,
  receptor,
  sender,
  receiver,
  group_by,
  score = c("normalized", "raw"),
  point_size = 3,
  point_color = "dodgerblue4",
  add_regression = TRUE,
  title = NULL
)

Arguments

Value

A list containing:

• plot - ggplot object of the dotplot

• df - data frame used for plotting

Examples

# Dotplot of LR Score Against Continuous Group Variable
data(lr_scores_eg)
data(metadata_eg)
res <- dotplot_lr_continuous_group(
  lr_scores_eg, metadata_eg,
  ligand = "TAC4", receptor = "TACR1",
  sender = "Perivascular", receiver = "Cardiac",
  group_by = "IFNscore"
)

print(res$plot)
head(res$df)

Filter and Analyze Ligand-Receptor Pair Correlations (All Cell Types)

Description

Filters ligand-receptor (LR) pairs and analyzes their correlations for all possible cell type pairs, and returns significant LR pairs based on user-defined thresholds.

Usage

filter_lr_all(
  rna,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  min_cells = 50,
  min_samples = 10,
  min_cell_ratio = 0.1,
  min_sample_ratio = 0.1,
  cor_method = "spearman",
  adjust_method = "BH",
  min_adjust_p = 0.05,
  min_cor = 0,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

A data frame includes LR pairs with sufficient correlation and expression support across samples.

Rows are ordered by ascending adjust.p and descending cor.

Returns NULL if:

• No cell types are found in the metadata.

• Insufficient samples or cells remain after filtering.

• No ligand-receptor pairs pass the filtering thresholds.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Analyzing ligand-receptor interactions between all cell types
  result01a <- filter_lr_all(
    rna = seurat_object,
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(result01a)) {
  print(head(result01a))
  }

Filter and Analyze Ligand-Receptor Pair Correlations (Specified Sender and Receiver)

Description

Filters ligand-receptor (LR) pairs and analyzes their correlations for specified sender and receiver cell types, and returns significant LR pairs based on user-defined thresholds.

Usage

filter_lr_single(
  rna,
  sender,
  receiver,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  min_cells = 50,
  min_samples = 10,
  min_cell_ratio = 0.1,
  min_sample_ratio = 0.1,
  cor_method = "spearman",
  adjust_method = "BH",
  min_adjust_p = 0.05,
  min_cor = 0,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

A data frame includes LR pairs with sufficient correlation and expression support across samples.

Rows are ordered by ascending adjust.p and descending cor.

Returns NULL if:

• No cell types are found in the metadata.

• Insufficient samples or cells remain after filtering.

• No ligand-receptor pairs pass the filtering thresholds.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Analyzing ligand-receptor interactions: Cardiac -> Perivascular
  result01s <- filter_lr_single(
    rna = seurat_object,
    sender = "Cardiac",
    receiver = "Perivascular",
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(result01s)) {
  print(head(result01s))
  }

Example for filtered_lr

Description

Example for filtered_lr

Usage

filtered_lr_eg

Format

An object of class data.frame with 5904 rows and 12 columns.

Generate Heatmap of Ligand-Receptor Interaction Scores

Description

This function generates a heatmap to visualize the ligand-receptor (LR) interaction scores across samples. Rows represent LR pairs and columns represent samples. Optionally, sample metadata can be used to annotate the columns.

Usage

heatmap_sample(
  lr_scores,
  metadata,
  score = c("normalized", "raw"),
  selected_sender = NULL,
  selected_receiver = NULL,
  selected_metadata = NULL
)

Arguments

Value

Heatmap of average LR interaction scores per sample.

Examples

# Heatmap of LR Interaction Scores
data(lr_scores_eg)
data(metadata_eg)
p <- heatmap_sample(lr_scores_eg, metadata_eg, score = "normalized", selected_sender = "Cardiac",
  selected_receiver = "Perivascular", selected_metadata = c("Sex", "Age_group", "IFN_type"))
print(p)

Example Seurat Object for PopComm Package

Description

A preprocessed Seurat object containing single-cell RNA sequencing data for demonstration and testing purposes across functions in the PopComm package. The object includes normalized expression data, metadata with sample and cell type annotations, and basic preprocessing steps (e.g., dimensionality reduction).

Usage

load_example_seurat()

Format

A Seurat object with the following slots:

assays

RNA count matrix normalized by log1p.

meta.data

Dataframe containing metadata columns:

• sample: Sample identifier (e.g., "sample1", "sample2").

• broad.cell.type: Cell type annotations (e.g., "Cardiac", "Fibroblast").

reductions

PCA and UMAP embeddings for visualization.

Value

A Seurat object containing example single-cell RNA-seq data. If the download fails, the function returns NULL.

Source

Subset of snRNA-seq data analyzed in our study, processed via standard workflow (see manuscript for details). Full dataset available at Zenodo (DOI: 10.XXXX/zenodo.XXXXX).

Ligand-Receptor Pair Database

Description

A comprehensive database of human ligand-receptor pairs with gene/protein identifiers and supporting evidence from literature. Data imported from human_lr_pair.txt.

Usage

lr_db

Format

A data frame with 3,398 rows (pairs) and 10 columns:

lr_pair

Character. Unique identifier for ligand-receptor pair, formatted as "LIGAND_RECEPTOR" (e.g., "SEMA3F_PLXNA3")

ligand_gene_symbol

Character. Official HGNC symbol of the ligand gene (e.g., "SEMA3F")

receptor_gene_symbol

Character. Official HGNC symbol of the receptor gene (e.g., "PLXNA3")

ligand_gene_id

Integer. Entrez Gene ID of the ligand gene (NCBI identifier)

receptor_gene_id

Integer. Entrez Gene ID of the receptor gene (NCBI identifier)

ligand_ensembl_protein_id

Character. Ensembl protein ID of the ligand (e.g., "ENSP00000002829")

receptor_ensembl_protein_id

Character. Ensembl protein ID of the receptor (e.g., "ENSP00000358696")

ligand_ensembl_gene_id

Character. Ensembl gene ID of the ligand (e.g., "ENSG00000001617")

receptor_ensembl_gene_id

Character. Ensembl gene ID of the receptor (e.g., "ENSG00000130827")

evidence

Character. PubMed IDs (PMIDs) supporting the interaction, comma-separated (e.g., "15721238")

Source

Source from CellTalkDB (PMID: 33147626).

Compare Ligand-Receptor Interaction Scores with Group Variable using Linear Regression

Description

Perform linear regression analysis to compare ligand-receptor (LR) interaction scores across groups, handling both continuous and binary group variables (ident1 vs ident2 or all others).

Usage

lr_linear_model_discrete(
  lr_scores,
  metadata,
  group_variable,
  ident1,
  ident2 = NULL,
  covariates = NULL,
  fdr_threshold = 0.05
)

Arguments

Value

Data frame with ligand, receptor, sender, receiver, coef (coefficient, logFC), p-values, and adjusted p-values.

Examples

  # Long-running example (may take >10s)
  data(lr_scores_eg)
  data(metadata_eg)

  res <- lr_linear_model_discrete(
    lr_scores_eg, metadata_eg,
    group_variable = "IFN_type",
    ident1 = "high",
    covariates = c("Age_group", "Sex")
  )
  head(res)

Example for lr_scores

Description

Example for lr_scores

Usage

lr_scores_eg

Format

An object of class data.frame with 377006 rows and 15 columns.

Example for metadata

Description

Example for metadata

Usage

metadata_eg

Format

An object of class data.frame with 163 rows and 9 columns.

Analyze Ligand-Receptor Pair Correlations and Projection Scores (Across All Cell Types)

Description

Performs integrated analysis of ligand-receptor (LR) pairs through two consecutive phases:

1. Filters LR pairs and analyzes correlations across all cell types.

2. Calculates projection scores based on regression models for valid pairs. Returns comprehensive results combining statistical metrics.

Usage

one_step_all(
  rna,
  lr_database,
  sample_col,
  cell_type_col,
  min_cells = 50,
  min_samples = 10,
  min_cell_ratio = 0.1,
  min_sample_ratio = 0.1,
  cor_method = "spearman",
  adjust_method = "BH",
  min_adjust_p = 0.05,
  min_cor = 0,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

Two data frames with columns:

Returns NULL if:

• No cell types are found in the metadata.

• Insufficient samples or cells remain after filtering.

• No ligand-receptor pairs pass the filtering thresholds.

• One or both of the specified sender and receiver cell types are missing in the data.

• Fewer than two valid samples remain after filtering based on minimum cell number per sample.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Integrated analysis across all cell types
  res_all <- one_step_all(
    rna = seurat_object,
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(res_all)) {
    print(head(res_all$res1))
    print(head(res_all$res2))
  }

Analyze Ligand-Receptor Pair Correlations and Projection Scores (Specified Sender and Receiver)

Description

Performs integrated analysis of ligand-receptor (LR) pairs through two consecutive phases:

1. Filters LR pairs and analyzes correlations between specified cell types.

2. Calculates projection scores based on regression models for valid pairs. Returns comprehensive results combining statistical metrics.

Usage

one_step_single(
  rna,
  sender,
  receiver,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  min_cells = 50,
  min_samples = 10,
  min_cell_ratio = 0.1,
  min_sample_ratio = 0.1,
  cor_method = "spearman",
  adjust_method = "BH",
  min_adjust_p = 0.05,
  min_cor = 0,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

Two data frames with columns:

Returns NULL if:

• No cell types are found in the metadata.

• Insufficient samples or cells remain after filtering.

• No ligand-receptor pairs pass the filtering thresholds.

• One or both of the specified sender and receiver cell types are missing in the data.

• Fewer than two valid samples remain after filtering based on minimum cell number per sample.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Integrated analysis with Cardiac -> Perivascular
  res_single <- one_step_single(
    rna = seurat_object,
    sender = "Cardiac",
    receiver = "Perivascular",
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(res_single)) {
    print(head(res_single$res1))
    print(head(res_single$res2))
  }

Generate PCA of Ligand-Receptor Interaction Scores

Description

This function performs principal component analysis (PCA) on ligand-receptor (LR) interaction scores across samples, and generates a scatter plot of the first two principal components. Optionally, sample metadata can be used to color the points.

Usage

pca_sample(
  lr_scores,
  metadata,
  selected_sender = NULL,
  selected_receiver = NULL,
  color_by = NULL,
  n_components = 2
)

Arguments

Value

A list with two elements: the first is a ggplot2 PCA scatter plot and the second is the PCA results data frame.

Examples

# PCA of LR Interaction Scores
data(lr_scores_eg)
data(metadata_eg)
res <- pca_sample(lr_scores_eg, metadata_eg, selected_sender = "Cardiac",
  selected_receiver = "Perivascular", color_by = "IFN_type")

print(res$plot)
head(res$df)

Analyze Ligand-Receptor Projection Scores (Across All Cell Types)

Description

This function calculates the ligand-receptor (LR) projection scores between all combinations of sender and receiver cell types. The projection score is computed based on linear regression models, measuring the normalized distance of each sample's LR expression from the origin of the regression line.

Usage

score_lr_all(
  rna,
  filtered_lr,
  sample_col,
  cell_type_col,
  min_cells = 50,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

A data frame with projection scores per sample and LR pair. Columns:

Rows are ordered by filtered_lr columns and descending score.

Returns NULL if:

• No cell types are found in the metadata.

• One or both of the specified sender and receiver cell types are missing in the data.

• Fewer than two valid samples remain after filtering based on minimum cell number per sample.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Analyzing ligand-receptor interactions between all cell types
  result01a <- filter_lr_all(
    rna = seurat_object,
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  # Analyzing ligand-receptor projection scores between all cell types
  result02a <- score_lr_all(
    rna = seurat_object,
    filtered_lr = result01a,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(result02a)) {
  print(head(result02a))
  }

Analyze Ligand-Receptor Projection Scores (Specified Sender and Receiver)

Description

This function calculates the projection scores for ligand-receptor (LR) pairs between specified sender and receiver cell types. The projection score is computed based on linear regression models, measuring the normalized distance of each sample's LR expression from the origin of the regression line.

Usage

score_lr_single(
  rna,
  sender,
  receiver,
  filtered_lr,
  sample_col,
  cell_type_col,
  min_cells = 50,
  num_cores = 10,
  verbose = TRUE
)

Arguments

Value

A data frame with projection scores per sample and LR pair. Columns:

Rows are ordered by filtered_lr columns and descending score.

Returns NULL if:

• No cell types are found in the metadata.

• One or both of the specified sender and receiver cell types are missing in the data.

• Fewer than two valid samples remain after filtering based on minimum cell number per sample.

Examples

  # Long-running example (may take >10s)
  seurat_object <- load_example_seurat()
  data(lr_db)

  # Analyzing ligand-receptor interactions: Cardiac -> Perivascular
  result01s <- filter_lr_single(
    rna = seurat_object,
    sender = "Cardiac",
    receiver = "Perivascular",
    lr_database = lr_db,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    min_samples = 10,
    min_adjust_p = 0.5,
    num_cores = 1,
    verbose = TRUE
  )

  # Analyzing ligand-receptor projection scores: Cardiac -> Perivascular
  result02s <- score_lr_single(
    rna = seurat_object,
    sender = "Cardiac",
    receiver = "Perivascular",
    filtered_lr = result01s,
    sample_col = "sample",
    cell_type_col = "cell.type",
    min_cells = 20,
    num_cores = 1,
    verbose = TRUE
  )

  if (!is.null(result02s)) {
  print(head(result02s))
  }