Quality control for flow, spectral, and mass cytometry - time-based anomaly cleaning (flowAI, flowCut, PeacoQC, flowClean), margin/boundary event removal, signal-drift detection, dead-cell exclusion, CyTOF Gaussian/DNA/event-length checks, instrument calibration/standardization (MESF, CS&T, peak-2), and batch-level outlier flagging. Use when assessing acquisition quality, choosing a cleaning tool, ordering QC relative to compensation, deciding margin removal before density-based steps, or flagging problematic samples before clustering or differential analysis.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Quality control for flow, spectral, and mass cytometry - time-based anomaly cleaning (flowAI, flowCut, PeacoQC, flowClean), margin/boundary event removal, signal-drift detection, dead-cell exclusion, CyTOF Gaussian/DNA/event-length checks, instrument calibration/standardization (MESF, CS&T, peak-2), and batch-level outlier flagging. Use when assessing acquisition quality, choosing a cleaning tool, ordering QC relative to compensation, deciding margin removal before density-based steps, or flagging problematic samples before clustering or differential analysis.
Before using code patterns, verify installed versions match. If versions differ:
R: packageVersion('<pkg>') then ?function_name to verify parameters
Counterintuitive defaults to confirm: flowAI checks are FR/FS/FM (FM = dynamic range, not "flow"); PeacoQC MAD/IT_limit are LESS strict when HIGHER. Verify with ?flow_auto_qc and ?PeacoQC before tuning.
Cytometry QC
"Run quality control on my cytometry data" -> Detect and remove acquisition artifacts (flow-rate instability, signal drift, margin events, dead cells, CyTOF doublets) on the Time axis, then flag outlier samples.
R (flow/spectral): flowAI::flow_auto_qc(), PeacoQC::PeacoQC() (+ RemoveMargins())
R (mass): CATALYST::normCytof() beads + Gaussian/DNA/event-length gating
The Single Most Important Modern Insight -- The Time Parameter Is the Master QC Axis, and Order Matters
Nearly every acquisition artifact - clogs, bubbles, flow-rate surges, electronics warm-up, CyTOF sensitivity decay, oxide buildup - manifests as a CHANGE IN SIGNAL versus the Time channel. flowAI, flowCut, flowClean, and PeacoQC are all, at heart, Time-vs-signal anomaly detectors; a missing or mis-scaled $TIMESTEP silently degrades or breaks all of them. Just as important is the ORDER: compensation/unmixing -> transform -> margin removal -> time-based QC -> debris/doublet/dead-cell gating -> batch normalization. Margin (boundary) events piled at a detector min/max form spurious high-density ridges that fool density-based cleaning and density gates, so they must be stripped BEFORE any density step; and time-based QC on untransformed data misbehaves because the density structure the algorithms rely on lives on the transformed scale.
Cleaning-Tool Taxonomy
Tool
Citation
Mechanism
When to use / caveat
flowAI
Monaco 2016 Bioinformatics 32:2473
3 checks: flow rate (FR), signal acquisition (FS), dynamic range (FM)
classic; known AGGRESSIVE - can remove normal data
PeacoQC
Emmaneel 2022 Cytometry A 101:325
per-channel density peaks + MAD + isolation tree
only tool validated across flow + mass + spectral; QC engine of CytoPipeline
flowCut
Meskas 2023 Cytometry A 103:71
segments Time, removes low-density/deviant segments
less aggressive than flowAI; flags whole files
flowClean
Fletez-Brant 2016 Cytometry A 89:461
tracks subset frequency in centered-log-ratio space
floor ~30,000 events; writes a "GoodVsBad" parameter to gate on
Run flowAI (with the correct API)
Goal: Auto-clean a sample for flow-rate, signal-acquisition, and dynamic-range anomalies.
Approach:flow_auto_qc() returns a flowFrame of high-quality events when output=1; FM is the dynamic-range check; supply timeCh for concatenated/clock-reset files. flowAI is the time-based QC step - run it after compensation/transform/margin removal (per the ordering above), not on a raw uncompensated frame.
Goal: Remove boundary events, then clean unstable time/peak structure across all channels.
Approach:RemoveMargins() strips detector-min/max events; then PeacoQC() - remember higher MAD/IT_limit = LESS strict.
library(PeacoQC)
ff_nm <- RemoveMargins(ff, channels =c('FSC-A','SSC-A'))# do this BEFORE density QC
res <- PeacoQC(ff_nm, channels = marker_channels,
MAD =6, IT_limit =0.55,# defaults; higher = less strict (counterintuitive)
save_fcs =FALSE, plot =TRUE)
ff_clean <- res$FinalFF
Dead-Cell, Drift, and CyTOF Checks
Goal: Exclude dead cells, detect per-channel drift, and apply CyTOF-specific gates.
Approach: Viability dye threshold (bimodal); per-time-bin median slope for drift; for CyTOF use DNA intercalator + Gaussian/event-length; EQ-bead-median-vs-Time is the primary CyTOF drift readout (see bead-normalization).
expr <- exprs(ff)# dead cells take up more viability dye -> cut at the bimodal density VALLEY (data-driven), not a fixed quantile
dead_cut <- flowDensity::deGate(ff, channel ='Live_Dead')
live <- expr[,'Live_Dead']< dead_cut
# CyTOF single-cell gatesif('Event_length'%in% colnames(expr)){
keep <- expr[,'Event_length']>=10& expr[,'Event_length']<=75# confirm range per instrument}
dna <- grep('Ir191|Ir193', colnames(expr), value =TRUE)# intercalator-positive = nucleated
Calibration and Standardization (cross-study comparability)
A discovery analyst often skips this, but cross-experiment/cross-site MFI comparison is meaningless without it (Maecker & Trotter 2006 Cytometry A 69:1037):
MESF / MEF / ERF beads express intensity in molecules-of-equivalent-fluorochrome - comparable across instruments and time (NIST/ISAC standard; PE/Pacific Blue use ERF surrogates).
Quantibrite PE (defined PE molecules/bead, ~1:1 conjugation) converts MFI to antibodies-bound-per-cell / receptor density (bead values are LOT-dependent).
CS&T / 8-peak rainbow beads for daily QC (laser delay, area scaling, linearity).
Peak-2 / voltration: run a dim particle across PMT voltages, pick the CV-vs-voltage inflection = minimum voltage for optimal resolution. This is why MIFlowCyt mandates reporting voltages.
Batch-Level Outlier Flagging
Goal: Flag samples whose event count, flow stability, or marker medians deviate from the batch.
Approach: Per-file metrics + MAD-based bounds; track an anchor/reference sample if present.
Trigger: PeacoQC/flowClean before RemoveMargins. Mechanism: axis pile-ups are false high-density ridges. Symptom: real events removed near the boundary, or margins kept. Fix: remove margins first.
flowAI over-removal
Trigger: default flowAI on a low-rate or short acquisition. Mechanism: FR check flags normal slow segments. Symptom: large unexplained event loss. Fix: raise second_fractionFR; inspect the HTML report; consider flowCut/PeacoQC.
QC on untransformed/uncompensated data
Trigger: running QC on raw linear values. Mechanism: high-intensity tail dominates density. Symptom: misplaced anomaly calls. Fix: compensate + transform first.
Time axis missing/reset
Trigger: concatenated files, some sorters. Mechanism: no usable Time. Symptom: flow-rate check fails or is meaningless. Fix:timeCh= or reconstruct; otherwise skip time-based checks.
Quantitative Thresholds
Threshold
Source
Rationale
flowClean floor ~30,000 events
Fletez-Brant 2016 Cytometry A 89:461
below this the CLR frequency tracking under-detects
PeacoQC MAD=6, IT_limit=0.55
Emmaneel 2022 Cytometry A 101:325
defaults; HIGHER = less strict
dead cells > ~10-30%
community
sample-handling flag, not a hard cutoff - report, don't auto-exclude the sample
CyTOF retune ~ daily / per long run
instrument practice (flagged)
sensitivity decays from cone fouling/plasma drift
Common Errors
Error / symptom
Cause
Solution
flow_auto_qc returns unexpected object
assuming $fcs/report list
output=1 returns a flowFrame; set output explicitly
