Introduction to ConvergeR

In ConvergeR: Whitfield Convergence Score and Seurat Metadata Association

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = TRUE
)

Introduction

ConvergeR is an analytical toolkit designed to compute, visualize, and statistically evaluate the convergence of single-cell states, based on the methodology established by Whitfield et al. (2026).

In this vignette, we will demonstrate the package workflow using a full dataset of 3,000 Peripheral Blood Mononuclear Cells (PBMC). We will evaluate cells for their balance between two opposing states: Immune Signaling UP versus Immune Signaling DN from MSigDB.

1. Environment Setup and Data Preparation

Let's load the required packages and the lightweight subset of the PBMC dataset bundled with the package.

library(ConvergeR)
library(Seurat)
library(ggplot2)

# Load the built-in example dataset
seu_path <- system.file("extdata", "pbmc3k_subset.rds", package = "ConvergeR")
seu <- readRDS(seu_path)

# Normalising
seu <- NormalizeData(seu, verbose = FALSE)

# Inject mock clinical metadata to simulate a multi-patient cohort
set.seed(42)
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$SS <- paste0("Patient_", sample(1:5, ncol(seu), replace = TRUE))

2. Importing MSigDB Signatures and Scoring

Instead of manually importing .gmt files, we use the msigdbr package to directly retrieve the official Hallmark Immune signatures.

library(msigdbr)

# S'assurer que l'on travaille sur l'assay RNA principal
DefaultAssay(seu) <- "RNA"

# Récupérer deux signatures immunitaires/inflammatoires bien exprimées dans les PBMC
hallmark_sets <- msigdbr(species = "Homo sapiens", category = "H")

raw_group1 <- hallmark_sets[hallmark_sets$gs_name == "HALLMARK_INTERFERON_ALPHA_RESPONSE", ]$gene_symbol
raw_group2 <- hallmark_sets[hallmark_sets$gs_name == "HALLMARK_INFLAMMATORY_RESPONSE", ]$gene_symbol

# Intersection stricte avec les gènes réellement présents dans pbmc3k_subset
group1_genes <- intersect(raw_group1, rownames(seu))
group2_genes <- intersect(raw_group2, rownames(seu))

# Calcul des scores de modules Seurat
seu <- AddModuleScore(seu, features = list(group1_genes), name = "Score_IFN_")
seu <- AddModuleScore(seu, features = list(group2_genes), name = "Score_Inflam_")

# Renommer proprement les colonnes pour la suite
seu$Score_IFN <- seu$Score_IFN_1
seu$Score_Inflam <- seu$Score_Inflam_1

3. Computing the Convergence Score

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", # Violet pour Interféron
  other_color = "#e67e22"      # Orange pour Inflammatoire
)

4. Visualization

ConvergeR automatically reads the color metadata generated in the previous step to produce standardized plots.

Proportion Barplot

Proportion of cells converging to either Immune state across our 10 mock patients.

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

Crossed Proportion Barplot

Faceted by tumor status to identify subgroup trends.

PlotConvergenceCrossedProportion(
  seurat_obj = seu, 
  x_var = "SS",
  fill_var = "Converged_Immune_Direction",
  facet_var = "tumor_status",
  title = "Immune Convergence split by Tumor Status"
)

Density Distribution

Continuous relationship of the convergence direction with patient age.

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

5. Statistical Testing

We evaluate the statistical significance at the patient level (pseudobulk) to prevent pseudoreplication bias caused by single-cell testing.

Bivariate Test

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

How to read this result: The output message displays the statistical test used (e.g., Spearman correlation for continuous variables), the analysis level (patient pseudobulk to avoid single-cell pseudoreplication), the number of observations ($N$ patients), and the p-value. A p-value below 0.05 indicates a statistically significant association between the convergence score and the tested variable.

Multivariate Linear Model

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

How to read this result: This model fits a multivariable linear regression on pseudobulk data. It details the global model performance ($R^2$ and global p-value) and breaks down the independent effect (Estimate) and significance (p-value accompanied by conventional significance stars) for each covariate, allowing you to assess the effect of a variable while controlling for potential confounders.

Session Information

sessionInfo()

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