Compute Spillover Spreading Score (SS) Between Fluorophores

This function calculates the spillover spreading score (SS) between a primary fluorophore (f_pos) and a secondary fluorophore (f_neg) using precomputed SSM objects and an unmixing matrix A. It supports both built-in and custom SSM sources, and performs detector-to-fluorophore unmixing followed by quantile-based spread estimation.

Usage

check_ss(f_pos, f_neg, SSM_fluor, A, Userm, custom_ssm_dir = NULL, mSS = FALSE)

Arguments

f_pos

A character string specifying the positive fluorophore (positive channel).

f_neg

A character string specifying the negative fluorophore (negative channel).

SSM_fluor

A character vector of fluorophores required for SSM computation. Used for availability checks.

A

A numeric matrix representing the detector-to-fluorophore unmixing matrix. Row names must be detector names; column names must be fluorophore names.

custom_ssm_dir

Optional path to a directory containing custom SSM .rds files. Default is NULL.

mSS

Modified Spread error. Default is TRUE. If set to FALSE, original Spread error will be calculated.

Value

A list containing:

f_pos

positive fluorophore name.

f_neg

negative fluorophore name.

B_pos

Unmixed positive sample matrix (cells × fluorophores).

B_neg

Unmixed negative sample matrix (cells × fluorophores).

R_F_neg_84

84th percentile of f_neg in negative samples.

R_F_neg_50

Median of f_neg in negative samples.

R_sigma_F_neg

Spread of f_neg in negative samples.

S_F_neg_84

84th percentile of f_neg in positive samples.

S_F_neg_50

Median of f_neg in positive samples.

S_sigma_F_neg

Spread of f_neg in positive samples.

S_F_pos_50

Median of f_pos in positive samples.

R_F_pos_50

Median of f_pos in negative samples.

delta_F_pos

Difference in median signal of f_pos between positive and negative samples.

delta_sigma_F_neg_2

Difference in squared spread of f_neg between positive and negative samples.

ss_2

Intermediate SS score before square root transformation.

ss

Final spillover spreading score.

Details

For the detailed explanation of returned items, please refer to Fig1A of Nguyen, Perfetto et al. Quantifying Spillover Spreading for Comparing Instrument Performance and Aiding in Multicolor Panel Design”. Cytometry A. 2013.

The function loads SSM objects for the specified fluorophores, checks detector compatibility with the unmixing matrix, performs matrix inversion and unmixing, and computes quantile-based spread metrics. The SS score is derived from the change in spread of the negative channel (f_neg) relative to the signal increase in the positive channel (f_pos).

If f_pos == f_neg, the score is set to zero and all intermediate metrics are returned as NA.

Examples

if (FALSE) { # \dontrun{
A <- matrix(runif(25), nrow = 5)
rownames(A) <- paste0("Det", 1:5)
colnames(A) <- c("FITC", "PE", "APC", "PerCP", "BV421")
check_ss(f_pos = "FITC", f_neg = "PE", SSM_fluor = c("FITC", "PE"),
         A = A, custom_ssm_dir = "~/custom_ssm")
} # }