Title:	Population-Level Cell-Cell Communication Analysis Tools
Version:	1.0.0
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.
URL:	https://github.com/JusticeGO/PopComm
BugReports:	https://github.com/JusticeGO/PopComm/issues
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, cowplot (≥ 1.1.1)
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.2.3
LazyData:	true
NeedsCompilation:	no
Packaged:	2025-11-01 05:29:58 UTC; gongz
Author:	Zheng Gong [aut, cre], Mengwei Li [aut, ctb]
Maintainer:	Zheng Gong <gongzheng131@hotmail.com>
Repository:	CRAN
Date/Publication:	2025-11-01 22:00:02 UTC

Boxplot Comparison of Ligand-Receptor Interaction Scores Across Groups

Description

Generates a boxplot comparing ligand-receptor (LR) 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 = lr_scores_eg,
  metadata = metadata_eg,
  ligand = "PSAP",
  receptor = "LRP1",
  sender = "Perivascular",
  receiver = "Fibroblast",
  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 ggplot object representing the network plot.

Examples

# Plot Circular Cell-Cell Interaction Network
data(filtered_lr_eg)

p <- circle_plot(
  filtered_lr = 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 = filtered_lr_eg,
  top_n = 3,
  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 ligand-receptor (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 = lr_scores_eg,
  metadata = metadata_eg,
  ligand = "HLA-A",
  receptor = "LILRB2",
  sender = "Lymphoid",
  receiver = "Myeloid",
  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. This function supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names).

Usage

filter_lr_all(
  rna,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  id_sep,
  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,
  min_r2 = 0,
  min_fstat = 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

  data(matrix_object)
  data(lr_db)

  # Analyzing ligand-receptor interactions between all cell types
  result01a <- filter_lr_all(
    rna = matrix_object,
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    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. This function supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names).

Usage

filter_lr_single(
  rna,
  sender,
  receiver,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  id_sep,
  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,
  min_r2 = 0,
  min_fstat = 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

  data(matrix_object)
  data(lr_db)

  # Analyzing ligand-receptor interactions: Perivascular -> Endothelial
  result01s <- filter_lr_single(
    rna = matrix_object,
    sender = "Perivascular",
    receiver = "Endothelial",
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    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 1513 rows and 11 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,
  treeheight_row = 50,
  treeheight_col = 50,
  show_LR = FALSE,
  show_sample = FALSE,
  basic_title = NULL
)

Arguments

Value

A pheatmap object.

Examples

# Heatmap of LR Interaction Scores
data(lr_scores_eg)
data(metadata_eg)

p <- heatmap_sample(
  lr_scores = lr_scores_eg,
  metadata = metadata_eg,
  score = "normalized",
  selected_sender = "Endothelial",
  selected_receiver = "Perivascular",
  selected_metadata = c("Sex", "Age_group", "IFN_type")
  )

print(p)

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. CellTalkDB: A manually curated database of ligand-receptor interactions in human and mouse

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, p-values, and adjusted p-values.

Examples

  data(lr_scores_eg)
  data(metadata_eg)

  res <- lr_linear_model_discrete(
    lr_scores = lr_scores_eg,
    metadata = 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 187593 rows and 14 columns.

Example for matrix object

Description

Example for matrix object

Usage

matrix_object

Format

An object of class matrix (inherits from array) with 223 rows and 144 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. This function supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names).

Usage

one_step_all(
  rna,
  lr_database,
  sample_col,
  cell_type_col,
  id_sep,
  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,
  min_r2 = 0,
  min_fstat = 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

  data(matrix_object)
  data(lr_db)

  # Integrated analysis across all cell types
  res_all <- one_step_all(
    rna = matrix_object,
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    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. This function supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names).

Usage

one_step_single(
  rna,
  sender,
  receiver,
  lr_database = PopComm::lr_db,
  sample_col,
  cell_type_col,
  id_sep,
  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,
  min_r2 = 0,
  min_fstat = 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

  data(matrix_object)
  data(lr_db)

  # Integrated analysis with Perivascular -> Endothelial
  res_single <- one_step_single(
    rna = matrix_object,
    sender = "Perivascular",
    receiver = "Endothelial",
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    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 containing:

• plot - ggplot object of the PCA scatter plot

• df - data frame used for the PCA results

Examples

# PCA of LR Interaction Scores
data(lr_scores_eg)
data(metadata_eg)

res <- pca_sample(
  lr_scores = lr_scores_eg,
  metadata = metadata_eg,
  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, and it supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names). 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,
  id_sep,
  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

  data(matrix_object)
  data(lr_db)

  # Analyzing ligand-receptor interactions between all cell types
  result01a <- filter_lr_all(
    rna = matrix_object,
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    num_cores = 1,
    verbose = TRUE
    )

  # Analyzing ligand-receptor projection scores between all cell types
  result02a <- score_lr_all(
    rna = matrix_object,
    filtered_lr = result01a,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    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, and it supports both Seurat objects and average expression matrices (matrix of gene expression data with cell types and samples as column names). 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,
  id_sep,
  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

  data(matrix_object)
  data(lr_db)

  # Analyzing ligand-receptor interactions: Perivascular -> Endothelial
  result01s <- filter_lr_single(
    rna = matrix_object,
    sender = "Perivascular",
    receiver = "Endothelial",
    lr_database = lr_db,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    min_samples = 10,
    min_sample_ratio = 0.1,
    min_adjust_p = 0.05,
    num_cores = 1,
    verbose = TRUE
    )

  # Analyzing ligand-receptor projection scores: Perivascular -> Endothelial
  result02s <- score_lr_single(
    rna = matrix_object,
    sender = "Perivascular",
    receiver = "Endothelial",
    filtered_lr = result01s,
    sample_col = 2,
    cell_type_col = 1,
    id_sep = "--",
    num_cores = 1,
    verbose = TRUE
    )

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