Version Compatibility

Reference examples tested with: flowCore 2.14+, flowStats 4.14+, flowWorkspace 4.14+, CATALYST 1.26+.

Before using code patterns, verify installed versions match. If versions differ:

• R: packageVersion('<pkg>') then ?function_name to verify parameters

Notes that bite: estimateLogicle() lives in flowWorkspace (not flowCore). flowCore::spillover() on a flowFrame returns a LIST of keyword matrices (index [[1]]); flowStats::spillover() on single-stain controls returns the matrix DIRECTLY (not a list) - do not index it with $.

If code throws an error, introspect the installed package and adapt rather than retrying.

Compensation and Transformation

"Compensate and transform my cytometry data" -> Remove spillover (matrix subtraction, conventional) or unmix the full spectrum (least squares, spectral), then apply a transform so populations separate.

• R (conventional): flowCore::compensate() then flowWorkspace::estimateLogicle() + flowCore::transform()
• R (CyTOF/mass): CATALYST::prepData(..., transform=TRUE, cofactor=5) (arcsinh)
• R (spectral): linear UNMIXING, not compensation - see the taxonomy

The Single Most Important Modern Insight -- Compensation Corrects the Mean; It Cannot Remove Spreading Error

Conventional compensation inverts a square spillover matrix (peak-channel subtraction); spectral cytometry solves an OVERDETERMINED least-squares unmix over all detectors, with autofluorescence modeled as an extra "fluorophore." Both correct the population MEAN. Neither removes spreading error - the widening of a negative population in a spillover detector that arises from the Poisson counting statistics of the spilled-in photons (Roederer 2001 Cytometry 45:194; Nguyen 2013 Cytometry A 83:306). Compensation does not INTRODUCE spreading; it makes the pre-existing variance visible by re-centering means. The corollaries are load-bearing: (1) a smeared negative cannot be fixed by tuning the matrix - over-compensating to flatten it is data falsification; (2) spreading is fixed at PANEL DESIGN (the Spillover Spreading Matrix identifies which detector pairs to avoid for co-expressed/dim markers), never downstream; (3) calling spectral unmixing "compensation" is a category error - it is a different, overdetermined model.

Method Taxonomy

Decision Tree by Scenario

Compensate-Then-Transform Ordering (load-bearing)

Compensation/unmixing is LINEAR and must run on untransformed data; applying it after a nonlinear transform is mathematically invalid. estimateLogicle() must run on ALREADY-COMPENSATED data so the w/a parameters reflect the post-compensation negative spread. Negative values after compensation are expected and meaningful - do NOT clip to zero before transforming (handling negatives is the entire reason logicle/arcsinh exist; log cannot).

Apply or Compute Compensation

Goal: Apply the recorded matrix, or estimate one from single-stain controls.

Approach: compensate() takes a compensation object built from the matrix; flowStats::spillover() estimates from single-stain controls and returns the matrix directly.

library(flowCore)

comp <- compensation(spillover(fcs)[[1]])      # flowCore: flowFrame -> list of keyword matrices
fcs_comp <- compensate(fcs, comp)

library(flowStats)
ctrls <- read.flowSet(list.files('controls', pattern = '\\.fcs$', full.names = TRUE))
comp_matrix <- spillover(ctrls, unstained = 'Unstained.fcs', fsc = 'FSC-A', ssc = 'SSC-A',
                         patt = '-A$', method = 'median')   # flowStats: returns the matrix directly

Logicle / Biexponential Transform (fluorescence)

Goal: Display and analyze compensated fluorescence with negatives handled honestly.

Approach: estimateLogicle() (flowWorkspace) derives w from the data's most-negative events; apply with transform().

library(flowWorkspace)

fluo <- colnames(fcs_comp)[grepl('-A$', colnames(fcs_comp)) & !grepl('FSC|SSC', colnames(fcs_comp))]
lgcl <- estimateLogicle(fcs_comp, channels = fluo)   # data-driven w; t=262144, m=4.5, a=0 defaults
fcs_t <- transform(fcs_comp, lgcl)

Arcsinh Transform (CyTOF cofactor 5; fluorescence/spectral ~150 or per-channel)

Goal: Variance-stabilize mass-cytometry counts (or any pipeline feeding clustering).

Approach: asinh(x/cofactor); flowCore's arcsinhTransform is asinh(a + b*x) + c, so set b=1/cofactor. CATALYST prepData defaults cofactor=5.

COFACTOR <- 5      # standard CyTOF cofactor, codified in the CATALYST workflow (Nowicka 2017); ~150 for fluorescence

asinhT <- arcsinhTransform(transformationId = 'asinh', a = 0, b = 1/COFACTOR, c = 0)
fcs_t  <- transform(fcs, transformList(marker_channels, asinhT))

# CATALYST path (CyTOF): cofactor=5 default; OVERRIDE for fluorescence/spectral
sce <- CATALYST::prepData(fs, panel, md, transform = TRUE, cofactor = COFACTOR)

Per-Method Failure Modes

Over-compensation (negative pull-down)

Trigger: matrix slope over-estimated from dim controls. Mechanism: subtraction overshoots. Symptom: negative population pulled below zero, "comma" shape. Fix: controls at least as bright as the sample; AutoSpill regression; never hand-tune to flatten spread.

Wrong logicle width clips negatives

Trigger: fixed w instead of estimateLogicle. Mechanism: linear region too narrow. Symptom: negative population piled on the axis. Fix: estimate w on compensated data.

Cofactor compresses a dim marker

Trigger: cofactor 5 on fluorescence (or 150 on CyTOF). Mechanism: linear region mismatched to the noise band. Symptom: dim-positive collapses into the negative; clusters don't reproduce. Fix: 5 for CyTOF, ~150 for fluorescence; per-channel via flowVS::estParamFlowVS.

Compensating spectral data

Trigger: treating Aurora data as conventional. Mechanism: subtraction is the wrong model for an overdetermined system. Symptom: residual spread, false positives. Fix: unmix against single-stain reference spectra + unstained AF.

Quantitative Thresholds

Common Errors

References

• Roederer 2001 Cytometry 45(3):194-205 — spreading error / compensation artifacts.
• Nguyen 2013 Cytometry A 83(3):306-315 — spillover spreading matrix; panel design.
• Roca 2021 Nat Commun 12:2890 — AutoSpill robust-regression compensation.
• Parks 2006 Cytometry A 69(6):541-551 — logicle display.
• Moore & Parks 2012 Cytometry A 81(4):273-277 — logicle operational update.
• Bendall 2011 Science 332(6030):687-696 — CyTOF mass cytometry; arcsinh-median analysis.
• Nowicka 2017 F1000Research 6:748 — CATALYST workflow; codifies the cofactor-5 convention.
• Azad 2016 BMC Bioinformatics 17:291 — flowVS per-channel cofactor.
• Chevrier 2018 Cell Syst 6(5):612-620 — CyTOF spillover compensation (CATALYST).

Related Skills

• fcs-handling - Load FCS and retrieve the spillover keyword first
• gating-analysis - Gate on the transformed, compensated scale
• clustering-phenotyping - Cluster compensated, transformed data
• cytometry-qc - QC before and after preprocessing
• imaging-mass-cytometry/data-preprocessing - Shared arcsinh/metal-channel conventions
• spatial-transcriptomics/spatial-proteomics - Spectral/metal unmixing context