Package 'ConvergeR'

Calculate Converged Score

Description

Computes a "convergence score" comparing two groups of Seurat module scores. Each group can be made of a single score or a combination of several scores; the underlying methodology is identical either way.

Usage

CalculateConvergedScore(
  seurat_obj,
  principal_score,
  other_scores,
  principal_name = "Principal",
  other_name = "Other",
  output_colname = "Converged_Score",
  direction_colname = NULL,
  color_colname = NULL,
  principal_color = "#2ecc71",
  other_color = "#e74c3c"
)

Arguments

seurat_obj	Seurat object. Its meta.data must already contain the score columns.
principal_score	Character. Name of one score, OR a character vector naming several scores.
other_scores	Character. Same as principal_score, but for the group compared against.
principal_name	Character. Human-readable label (default: "Principal").
other_name	Character. Human-readable label (default: "Other").
output_colname	Character. Name of the column for the score (default: "Converged_Score").
direction_colname	Character or NULL. Name of the interpretation column.
color_colname	Character or NULL. Name of the hex color column.
principal_color	Character. Hex color for principal group (default: "#2ecc71").
other_color	Character. Hex color for other group (default: "#e74c3c").

Value

The same Seurat object, with the convergence score columns added to meta.data.

References

Whitfield HJ, Anderson ND, Burke C, Groot Koerkamp MJ, Parks C, Ogbonnah T, Wood Y, Piapi A, Robertson E, Watt E, White A, De Noon S, Kennedy J, Nagrecha R, Meister MT, Aladowicz E, Man YKS, Laspidea V, Trinh MK, Hodder A, Porter T, Lawrence JE, Tuck E, Nguyen T, Kelsey A, Flanagan AM, Hewitt R, Smeulders N, Slater O, Hutchinson JC, Sebire N, Shipley JM, Drost J, Straathof K, Behjati S. High-Risk Rhabdomyosarcomas Feature a Convergent Cell State. Cancer Res. 2026 Jul 14. doi: 10.1158/0008-5472.CAN-25-4403. PMID: 42446905.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)

# Simulated module scores (fast)
set.seed(42)
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  principal_name = "Interferon",
  other_name = "Inflammatory",
  output_colname = "Converged_Immune",
  principal_color = "#9b59b6",
  other_color = "#e67e22"
)
head(seu@meta.data[, c("Converged_Immune", "Converged_Immune_Direction")])


# Full workflow with MSigDB signatures (slower, requires msigdbr)
if (requireNamespace("msigdbr", quietly = TRUE)) {
  seu <- Seurat::NormalizeData(seu, verbose = FALSE)
  hs <- msigdbr::msigdbr(species = "Homo sapiens", category = "H")
  raw_group1 <- hs[hs$gs_name == "HALLMARK_INTERFERON_ALPHA_RESPONSE", ]$gene_symbol
  raw_group2 <- hs[hs$gs_name == "HALLMARK_INFLAMMATORY_RESPONSE", ]$gene_symbol

  group1_genes <- intersect(raw_group1, rownames(seu))
  group2_genes <- intersect(raw_group2, rownames(seu))

  seu <- Seurat::AddModuleScore(seu, features = list(group1_genes), name = "Score_IFN_")
  seu <- Seurat::AddModuleScore(seu, features = list(group2_genes), name = "Score_Inflam_")
  seu$Score_IFN <- seu$Score_IFN_1
  seu$Score_Inflam <- seu$Score_Inflam_1

  seu <- CalculateConvergedScore(
    seurat_obj = seu,
    principal_score = "Score_IFN",
    other_scores = "Score_Inflam",
    output_colname = "Converged_Immune_MSigDB"
  )
}

---

Plot Convergence Crossed Proportion

Description

Draws a 100%-stacked barplot of cell proportions across categories of x_var, colored by a convergence-direction column, and separated (faceted) by a secondary categorical variable (facet_var).

Usage

PlotConvergenceCrossedProportion(
  seurat_obj,
  x_var,
  fill_var,
  facet_var,
  color_var = NULL,
  title = NULL,
  x_label = NULL
)

Arguments

seurat_obj	Seurat object whose meta.data holds x_var, fill_var, facet_var, and the color column.
x_var	Character. Name of the meta.data column used on the x-axis.
fill_var	Character. Name of the meta.data column used to fill the bars.
facet_var	Character. Name of the meta.data column used to facet the plot (e.g., "tumor_status").
color_var	Character or NULL. Name of the meta.data column holding the hex color.
title	Character or NULL. Plot title.
x_label	Character or NULL. X-axis label.

Value

A ggplot object.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)
set.seed(42)
seu$SS <- paste0("Patient_", sample(1:5, ncol(seu), replace = TRUE))
seu$tumor_status <- sample(c("Primary", "Metastatic"), ncol(seu), replace = TRUE)
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  output_colname = "Converged_Immune"
)

b_cross <- PlotConvergenceCrossedProportion(
  seurat_obj = seu,
  x_var = "SS",
  fill_var = "Converged_Immune_Direction",
  facet_var = "tumor_status",
  title = "Immune Convergence split by Tumor Status",
  x_label = "Patient ID"
)
print(b_cross)

---

Plot Convergence Density

Description

Draws overlapping density curves of a continuous variable (x_var), split by a convergence-direction column (fill_var).

Usage

PlotConvergenceDensity(
  seurat_obj,
  x_var,
  fill_var,
  color_var = NULL,
  title = NULL,
  x_label = NULL,
  alpha = 0.6
)

Arguments

seurat_obj	Seurat object whose meta.data holds x_var, fill_var, and its matching color column.
x_var	Character. Name of the meta.data column holding the continuous variable (e.g. "age").
fill_var	Character. Name of the meta.data column used to fill the density curves.
color_var	Character or NULL. Name of the meta.data column holding the hex color.
title	Character or NULL. Plot title.
x_label	Character or NULL. X-axis label. Defaults to x_var.
alpha	Numeric. Transparency of the density fill, between 0 and 1 (default: 0.6).

Value

A ggplot object.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)
set.seed(42)
seu$age <- sample(20:70, ncol(seu), replace = TRUE)
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  output_colname = "Converged_Immune"
)

PlotConvergenceDensity(
  seurat_obj = seu,
  x_var = "age",
  fill_var = "Converged_Immune_Direction",
  x_label = "Patient Age"
)

---

Plot Convergence Proportion

Description

Draws a 100%-stacked barplot of cell proportions across categories of x_var, colored by a convergence-direction column (fill_var). The color mapping is extracted automatically from meta.data based on the color column generated by CalculateConvergedScore().

Usage

PlotConvergenceProportion(
  seurat_obj,
  x_var,
  fill_var,
  color_var = NULL,
  title = NULL
)

Arguments

seurat_obj	Seurat object whose meta.data holds both fill_var and its matching color column.
x_var	Character. Name of the meta.data column used on the x-axis (e.g. a patient identifier).
fill_var	Character. Name of the meta.data column used to fill the bars.
color_var	Character or NULL. Name of the meta.data column holding the hex color. Defaults to paste0(fill_var, "_Color").
title	Character or NULL. Plot title. Defaults to x_var.

Value

A ggplot object.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)
set.seed(42)
seu$SS <- paste0("Patient_", sample(1:5, ncol(seu), replace = TRUE))

# Simulate fast scores to ensure example runs efficiently
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  output_colname = "Converged_Immune"
)

p <- PlotConvergenceProportion(
  seurat_obj = seu,
  x_var = "SS",
  fill_var = "Converged_Immune_Direction",
  title = "Immune Convergence by Patient"
)
print(p)

---

Test Convergence Score

Description

Runs a statistical test between a numeric convergence score and another variable, automatically choosing the appropriate test (Spearman, Wilcoxon, or Kruskal-Wallis).

Usage

TestConvergenceScore(
  seurat_obj,
  score_var,
  test_var,
  level = c("cell", "patient"),
  patient_id_var = NULL
)

Arguments

seurat_obj	Seurat object whose meta.data holds score_var and test_var.
score_var	Character. Name of the meta.data column holding the numeric score.
test_var	Character. Name of the meta.data column to test the score against.
level	Character. Either "cell" (default) or "patient" (pseudobulk aggregation).
patient_id_var	Character. Name of the meta.data column identifying patients (required if level = "patient").

Value

The underlying htest object (invisibly). A message is printed summarizing the results.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)
set.seed(42)
seu$SS <- paste0("Patient_", sample(1:5, ncol(seu), replace = TRUE))
seu$age <- sample(20:70, ncol(seu), replace = TRUE)
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  output_colname = "Converged_Immune"
)

TestConvergenceScore(
  seurat_obj = seu,
  score_var = "Converged_Immune",
  test_var = "age",
  level = "patient",
  patient_id_var = "SS"
)

---

Test Multivariate Convergence

Description

Fits a multivariate linear model (lm) to test a numeric convergence score against multiple covariates simultaneously, correcting for confounding factors.

Usage

TestMultivariateConvergence(
  seurat_obj,
  score_var,
  test_vars,
  level = c("cell", "patient"),
  patient_id_var = NULL
)

Arguments

seurat_obj	Seurat object whose meta.data holds the variables.
score_var	Character. Name of the meta.data column holding the numeric score.
test_vars	Character vector. Names of the meta.data columns to include in the model.
level	Character. Either "cell" (default) or "patient" (pseudobulk aggregation).
patient_id_var	Character. Name of the meta.data column identifying patients (required if level = "patient").

Value

The summary.lm() object (invisibly). A detailed message is printed summarizing the model.

Examples

seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)
set.seed(42)
seu$SS <- paste0("Patient_", sample(1:5, ncol(seu), replace = TRUE))
seu$age <- sample(20:70, ncol(seu), replace = TRUE)
seu$tumor_status <- sample(c("Primary", "Metastatic"), ncol(seu), replace = TRUE)
seu$treatment <- sample(c("Treated", "Untreated"), ncol(seu), replace = TRUE)
seu$Score_IFN <- rnorm(ncol(seu))
seu$Score_Inflam <- rnorm(ncol(seu))

seu <- CalculateConvergedScore(
  seurat_obj = seu,
  principal_score = "Score_IFN",
  other_scores = "Score_Inflam",
  output_colname = "Converged_Immune"
)

TestMultivariateConvergence(
  seurat_obj = seu,
  score_var = "Converged_Immune",
  test_vars = c("age", "tumor_status", "treatment"),
  level = "patient",
  patient_id_var = "SS"
)

---