Flow cytometry

Open a flow cytometry list-mode file (.fcs), compensate it with its own spillover matrix, apply a Gating-ML 2.0 gating strategy, and read every population's size and per-channel intensity.

What it doesCopy Anchor Link

A flow cytometer measures every cell that passes its lasers once, in every detector at the same moment, and writes the result as a list: one row per event, one column per channel. Everything a flow analysis reports, from "CD4⁺ T cells were 42% of lymphocytes" to a median fluorescence intensity, is computed from that list by the same chain of steps. This tool performs each of them and shows its working.

Reading the file. An FCS file stores each channel either linearly or through a logarithmic amplifier. A 4-decade log channel on an older instrument stores the numbers 0 to 1,023 and means 1 to 10,000; reading the stored number as the intensity is a hundred-fold error at the top of the scale. The file says which it is ($PnE), and its gain ($PnG) and time step ($TIMESTEP); the tool applies all three as the FCS 3.1 standard prescribes before anything else happens.

Compensation. A dye emits across a range of wavelengths, so some of FITC's light reaches the PE detector, and some of PE's reaches PE-Cy5. The instrument measures this from single-stained controls and writes it into the file as a spillover matrix. Compensation removes it: each event's observed values are the true dye amounts mixed by that matrix, so the true amounts are found by solving the mixture back out. Two published algorithms are offered — solving each event's system directly (FlowKit's), or inverting the matrix once and multiplying (flowCore's). They agree to about one part in 10¹⁵ of full scale.

The display scale. Compensated values can be negative, and real populations span five decades, so neither a linear nor a log axis shows them. Logicle, ArcSinh and Hyperlog are the scales built for this: linear near zero, logarithmic far from it. The tool offers the eleven in use: the six Gating-ML 2.0 defines, FlowJo's log and biex, and flowCore's Logicle, arcsinh and biexponential.

Gating. A gate is a region in two (or more) channels, in a particular scale: the same polygon drawn on a Logicle axis and on a biex axis selects different cells. A Gating-ML 2.0 document records every gate with the compensation and scale of each of its dimensions, and this tool applies them as declared, then intersects each population with its parent.

What this computesCopy Anchor Link

• Linearised scale values — every event in every channel, through the channel's log amplification (10^(decades·channel/range)·offset), its gain, and the time step.
• Compensated intensities — each event with the spillover between detectors removed, by matrix solve (FlowKit) or inverse-matrix multiplication (flowCore).
• Display transforms — Logicle (Moore and Parks), ArcSinh, Hyperlog (Bagwell), linear, log and the ratio of two channels as Gating-ML 2.0 defines them; FlowJo's log and biex; flowCore's Logicle on a 0–M axis, arcsinh with a cofactor (asinh(x/c), the CyTOF and Cytobank convention) and biexponential.
• Gate membership — for rectangle, range and box gates (minimum inclusive, maximum exclusive), polygons (the even–odd rule, boundary inclusive), ellipses and ellipsoids (Mahalanobis distance within the stated radius), quadrants, and AND, OR and NOT combinations, each inside its parent population.
• Population size — every population's event count, percent of its parent and percent of all events.
• Per-channel statistics — the mean, median, standard deviation (n − 1) and coefficient of variation of every channel in every population, on linear compensated values (the MFI) or on the display scale, with the minimum and maximum.
• Two-channel density — any two channels of any population binned on a grid, coloured by log(1 + events per bin), with the gates on that pair drawn in the scale they were written in.
• Density-valley threshold — the cut points between the peaks of a channel's smoothed kernel density (flowDensity's deGate; one peak: its inflection point), on the display scale and as intensities, with the events above the last cut.
• Automated gates — openCyto's minimum-density cut (the valley between the two highest peaks of the kernel density), its spline-feature cut, a quantile cut, the sequential quadrant gate (the axis with the furthest-apart peaks cut first) and the singlet gate (a robust Huber regression of height on area and its prediction band), with the events on each side.
• Clustering — FlowSOM: a self-organizing map of the chosen channels, its nodes' minimum spanning tree, metaclusters by consensus hierarchical clustering, each node's marker medians and share of events, and the outlier report; the seed is shown and editable.
• Acquisition quality over time — flowAI (flow-rate anomalies, signal changepoints by binary segmentation, dynamic-range margins), PeacoQC (peak trajectories, isolation tree, MAD and short runs) and flowCut (deviant and low-density segments, the summed-measure gate), each with the events it removes and why.
• Spillover from controls — the spillover matrix estimated from single-stained control tubes and an unstained tube (median, mean or density mode per detector, baseline subtracted), with the tube-to-channel matching and every warning, drawn as a heatmap and as signatures.
• Derived parameters — new channels from expressions over existing ones: arithmetic, powers, logarithms, rounding and trigonometric functions, the ratio of two channels above all.
• Kinetics — a channel's median, mean, geometric mean, a percentile or the % of events above a threshold over acquisition time; the threshold as a value or a percentile of a time range; optional moving-average or Gaussian smoothing; per time range the peak and its time, mean, least-squares slope, area under the curve (trapezoid rule) and duration.
• Population comparison — one channel between two populations: Welch's two-sample t-test, the Wilcoxon rank-sum test (exact or with continuity correction, as R chooses), the two-sample Kolmogorov–Smirnov test (D and its p-value), Pearson's χ² on the two histograms over shared equal-width bins, and the probability binning comparison of Roederer et al. (2001): population A is cut into bins of equal event count by repeated median splits, B is counted in the same bins, and the normalised χ′², its expected value for one distribution (bins / events), its standard deviation and the T(χ) metric are reported (T(χ) above 4: the distributions differ with 99% confidence).
• Frequency of ancestors — each population as a percentage of its grandparent and of every ancestor gate up to the root.
• Metacluster diversity — Shannon, Simpson and inverse Simpson diversity of the events per FlowSOM metacluster.

Each step is checked against the field's reference implementations and against the standards' own published answers: the file reading against FlowIO; compensation against R's reference linear algebra and flowCore; the transforms against FlowUtils, FlowKit and flowCore and against the sample values printed in the Gating-ML 2.0 specification; gating against ISAC's expected answer for every event of all 80 gates in the Gating-ML 2.0 compliance suite; the thresholds against flowDensity; the automated gates against openCyto, the clustering against FlowSOM and ConsensusClusterPlus, and the quality checks against flowAI, PeacoQC and flowCut, all run in R on the same events; spillover from controls against flowStats; the hypothesis tests against R's own t.test, wilcox.test, ks.test and chisq.test, the probability bins against flowFP, and the diversity indices against vegan. Kinetics, derived parameters and the population comparison are assembled only from those checked statistics.

ControlsCopy Anchor Link

Compensation. Algorithm picks how the spillover is removed: solving each event's system (FlowKit's solve(Sᵀ, Xᵀ)) or multiplying by the inverted matrix once (flowCore's X · S⁻¹). A file with no spillover matrix says so instead of offering the choice.

Scale. Fluorescence scale is the display transform, one of the eleven above; the fields under it are that transform's own parameters, so only the ones it uses appear. T is the top of the scale, W the width of the linear region in decades, M (decades) the decades the axis spans, and A the extra negative decades kept below zero. The arcsinh with a cofactor takes one number, its Cofactor (5 is the CyTOF convention, 150 a common one for fluorescence). FlowJo's biex takes a Width basis (a negative number; more negative widens the linear region) and its own Extra negative decades. The line under the fields states the transform exactly as applied.

Gating. Gating-ML 2.0 strategy picks which strategy file in the project is applied, or none, in which case every event is one population.

Compare populations. The Channel, Population A (the control) and Population B; Histogram bins (χ²) for the χ² test; Probability-binning levels, the number of median splits (2ᴸ bins cut from A), or Auto, which takes flowFP's own rule (log₂ of A's event count, minus 3).

Plot. The two channels to plot, the population to draw, and Bins per axis (8–256): the grid the density is counted on. More bins resolve tighter populations and leave each bin with fewer events.

Reading the resultCopy Anchor Link

• Percent of parent and percent of total answer different questions. "CD4⁺ are 60% of CD3⁺" is percent of parent; "CD4⁺ are 25% of all events" is percent of total. Both are shown.
• A median is more robust than a mean for MFI. A few very bright or debris events move a mean a long way; the median of a few hundred events is stable. The CV says how spread the population is.
• An empty population has statistics that are undefined, not zero, and the explanation says so.
• A channel that reaches the top of its range has events piled at the axis whose true intensity is unknown; the explanation names it.
• A gate not drawn on the plot was defined on a different compensation than the plot shows, or on more than two dimensions; it is listed by name with the reason, and its population is still computed.

What it does not doCopy Anchor Link

A FlowJo workspace (.wsp), spectral unmixing with more detectors than dyes, clustering other than FlowSOM (PhenoGraph, and embeddings such as UMAP), batch analysis across many files, FlowJo's automatic kinetics ranges (their rule is not published), probability binning across several channels or several samples at once, and Overton cumulative subtraction are not part of this tool.