Estimate Spillover Spreading Matrix (SSM) from Unmixing and Control Data

Computes a full Spillover Spreading Matrix (SSM) for a set of fluorophores using precomputed positive/negative control data and an unmixing matrix. This matrix quantifies the extent of signal spreading from each fluorophore into others, aiding in panel design and instrument evaluation in spectral flow cytometry.

Usage

EstimateSSM(
  SSM_fluor,
  A,
  Userm,
  custom_ssm_dir = NULL,
  quiet = FALSE,
  mSS = FALSE
)

Arguments

SSM_fluor

A character vector of fluorophore names to include in the SSM. Each must have a corresponding SSMObj_*.rds file.

A

A numeric unmixing matrix (detectors × fluorophores) with row names as detector channels and column names as fluorophores.

custom_ssm_dir

Optional path to a directory containing custom SSMObj_*.rds files. If NULL, only built-in files from the USERM package are used.

Value

A numeric matrix of spillover spreading scores, with rows and columns named by SSM_fluor. Each entry ssm[i, j] represents the spreading from fluorophore i into fluorophore j. Diagonal entries are set to 0.

Details

For each fluorophore in SSM_fluor, the function loads its corresponding SSM object containing positive and negative control data. It performs detector-to-fluorophore unmixing using the pseudoinverse of matrix A, then calculates quantile-based spread metrics for each fluorophore pair.

The spillover spreading score is computed as: $$SS = \sqrt{(S_{\sigma}^2 - R_{\sigma}^2) / \Delta F}$$ where \(S_{\sigma}\) and \(R_{\sigma}\) are the 84th–50th percentile spreads in positive and negative samples, and \(\Delta F\) is the median signal increase in the primary fluorophore.

If \(\Delta F = 0\), the score is set to NA. Negative intermediate values yield imaginary scores, which are returned as negative square roots.

Examples

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