CalculateConvergedScore: Calculate Converged Score

In ConvergeR: Whitfield Convergence Score and Seurat Metadata Association

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([e-mail][, 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"
  )
}

ConvergeR documentation built on Oct. 10, 2026, 5:07 p.m.