Help for package ConvergeR

Title:

Whitfield Convergence Score and Seurat Metadata Association

Version:

0.99.1

Description:

Calculates the convergence score defined by Whitfield et al. 2026 <doi:10.1158/0008-5472.CAN-25-4403>. It allows visualization of this score alongside qualitative and quantitative Seurat object metadata via barplots and density curves, and runs appropriate statistical tests for associations.

Depends:

R (≥ 4.4.0)

License:

GPL-3

Encoding:

UTF-8

Imports:

dplyr, ggplot2, magrittr, scales, Seurat, SeuratObject

Config/roxygen2/version:

8.1.0

Suggests:

BiocStyle, knitr, msigdbr, rmarkdown, testthat (≥ 3.0.0)

Config/testthat/edition:

VignetteBuilder:

knitr

biocViews:

Software, SingleCell, Transcriptomics, GeneExpression

URL:

https://github.com/pauldeboissier1/ConvergeR

BugReports:

https://github.com/pauldeboissier1/ConvergeR/issues

NeedsCompilation:

Packaged:

2026-09-29 15:03:16 UTC; flavie

Author:

Paul de Boissier

[aut, cre]

Maintainer:

Paul de Boissier <paul.deboissier04@gmail.com>

Repository:

CRAN

Date/Publication:

2026-10-10 10:40:14 UTC

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"
)

Package {ConvergeR}

Calculate Converged Score

Description

Usage

Arguments

Value

References

Examples

Plot Convergence Crossed Proportion

Description

Usage

Arguments

Value

Examples

Plot Convergence Density

Description

Usage

Arguments

Value

Examples

Plot Convergence Proportion

Description

Usage

Arguments

Value

Examples

Test Convergence Score

Description

Usage

Arguments

Value

Examples

Test Multivariate Convergence

Description

Usage

Arguments

Value

Examples