Spectral unmixing¶
On a spectral cytometer each dye is measured across many detectors. Unmixing solves for the abundance of each dye in every event, given the reference spectra of the dyes. Because there are more detectors than dyes, the system is over-determined, and the choice of solver matters.
PlatAnJr splits this into two windows:
- The Unmixer - one panel per control file, where you say which file is which dye and where its positive and negative populations are. This produces the mixing matrix.
- The Unmixing Matrix window - where you inspect the matrix, choose a solver, run the unmixing and add the results to the dataset as parameters.
The Unmixer is opened from an Unmixer node in the gating graph: click Spectral Unmixing on the project panel toolbar to add one, link to its input the gates whose events are to be unmixed, and click the node's Unmix. The Unmixer works on the events reaching the node, and the gates feeding it are the populations each panel's Gate can pick. The box above the buttons is the node's Title, a name for it that the project keeps.
Choosing the channels¶
Select Pars on the node picks the parameters that take part; Unmix asks for them first when none are picked. Check the detectors that make up the spectrum and leave out scatter, time and anything already derived. The node keeps its choice in the project, and the last choice is remembered per data folder for the next node.
One panel per file¶
The Unmixer shows one horizontal panel per well, each carrying:
| Control | Purpose |
|---|---|
| Well and File Name | Which file this panel represents |
| Analyte | The marker or analyte name, used when naming the unmixed parameter |
| Stain | The fluorochrome this control stains for |
| File Destiny | Positive control, Negative control, or Sample |
| Gate | The gate restricting which events of this file are used: None, or one of the gates feeding the Unmixer node |
| Histogram Bin Count | Binning for the panel's own histogram |
| Background for this File | Which negative control supplies this file's background |
| Spectrum plot | The mean spectrum of the selected population across the checked channels |
| Statistics | Positive and negative medians, robust SD, total, and the resulting Stain Index |
Each file destiny is colour-coded, so a mis-assigned control is easy to spot.
Naming the controls¶
The two name fields are filled from the file name: PlatAnJr looks for a marker in the CD database and a dye in the spectra database, and puts the marker in Analyte and the dye in Stain. That is what the two fields always hold, however the Options are set; correct either by typing.
A viability control - Zombie NIR, LIVE DEAD Blue - gets Viability as its analyte and the viability dye as its stain. A dye or marker name counts only where it stands as a word of the file name, so a CD alias that happens to sit inside another word is not taken for a marker.
What the Plate Editor says of a well comes first: its type, analyte and dye fill the panel ahead of the file name, and ahead of an Unmixer node's saved configuration. What the unmixer reads from a file name, and what you change here, is written back to the Plate Editor at once and saved with the plate - so a correction made once stays made.
A comma becomes a hyphen, in either field, silently, with a note in the log: commas separate keywords in an FCS file, so a parameter name cannot hold one. Otherwise a field holds exactly what it says - two controls may share an analyte (beads and cells of the same stain, say), and the unmixed parameters are told apart where they are named: see below, and Add Unmixed Parameters, which numbers a repeated name.
A control whose file name says nothing recognisable keeps the file name as its analyte, so it is still named. A Sample has no single analyte, so its fields stay blank and out of the way.
When the unmixed data are saved (Save in the Unmixing Matrix window), each unmixed
parameter carries its control's analyte as $PnANALYTE and its stain as $PnTAG. Its name,
$PnN, and $PnS are the analyte and the stain by default, as the FCS standard means them;
software that reads them otherwise is catered for by For FCS standard violators on
Options ▸ Data. Whatever it is set to,
$PnN never holds a comma and is unique in the file: a name another parameter already
has - an earlier unmixed one, or a channel saved alongside - gets a number appended, and the
log says so.
Working efficiently¶
| Control | What it does |
|---|---|
| Show All | Reveal every panel again |
| Hide Samples | Collapse everything that is not a control, leaving only the panels that build the matrix |
| Sync Mode | Tick it, then change one control on one panel - the same change is copied to every panel, and the tick clears itself |
| Uniscale | Put every spectrum plot on one common Y range so spectra are directly comparable |
| Set Background For Positives / Set Background for Samples | Assign one negative control to all positives, or all samples, in one go |
| Show Stain Index Table | A table of stain index per dye - the quickest read on whether a control is any good |
| Save / Load | Save the whole Unmixer configuration (destinies, dyes, gates, backgrounds) into the data folder's INFO folder and read it back |
| Load Unmixed Par Names | Take the output parameter names from a file rather than typing them |
| Add Negatives to Unmixing Matrix | Include the negative-control spectra as columns, so autofluorescence is unmixed as if it were a dye |
Autofluorescence
On a spectral instrument, unmixing autofluorescence as an extra "dye" usually cleans up dim populations more than any change of solver will. That is what Add Negatives to Unmixing Matrix is for.
Getting the matrix¶
Click Get Unmixing Matrix. The Unmixing Matrix window opens with the Mixing Matrix - one column per dye, one row per detector - drawn as spectra and listed as numbers.
| Control | Purpose |
|---|---|
| Norm Spectra | How the reference spectra are normalised: None, Max Height = 1, L1 Norm or L2 Norm |
| Log (ArcSinh) | Plot both charts on an arcsinh Y scale: logarithmic for large values, linear and symmetric through zero so negatives still show. Axis labels stay in the original units |
| Export / Import | Matrix in and out as CSV |
| Add to DB / Get From DB | Store the spectra in, or fetch them from, the spectrum collection, so a dye measured once can be reused on later panels. Get From DB offers only the spectra your data can be unmixed with: see Spectra for a panel |
| Cosine / Angle | Pairwise similarity between the reference spectra - two dyes with a near-zero angle will be hard to separate no matter what solver you pick |
| mySSM | The spillover spreading matrix for this panel, from each positive control's own positive and negative gates - the background only takes the autofluorescence out of the spectrum |
Choosing a solver¶
The solver list offers seven options, in roughly increasing sophistication:
| Solver | When to use it |
|---|---|
| LSM | Plain least squares. Fast, and the reference everything else is compared against |
| WLSM | Weighted least squares - weights each detector by its variance, so noisy channels count for less. WLSM Average Variance switches between one variance for all channels and a per-channel estimate |
| Non Negative LSM | Least squares constrained to non-negative abundances |
| Pseudo Poisson | Weighted least squares with Poisson-like weights - a cheap approximation to the Poisson solver |
| Poisson | Full Poisson likelihood. Appropriate when the measurement really is photon counting |
| Negative Binomial | Poisson with over-dispersion, for detectors noisier than pure counting statistics |
| Sparse LSM | Non-negative least squares with rules on the answer: how many dyes a cell can carry, and how little of a dye counts. See Sparse LSM |
Supporting controls:
| Control | Effect |
|---|---|
| Fast Poisson / NB solver | Solves Poisson and Negative Binomial by multiplicative EM instead of Nelder-Mead. Same objective, orders of magnitude faster. Uncheck only to reproduce older results |
| Regularization - Ridge / Lasso | Penalise the abundance vector. Ridge shrinks everything smoothly; Lasso drives small abundances to exactly zero |
| Penalty | The regularisation strength |
| Map Negative Values | Map negative abundances into the 0..1 interval instead of leaving them negative |
Leave Fast Poisson on
The fast solver optimises the same objective as the slow one and reaches it far more quickly. The checkbox exists only for reproducing results generated before it was added.
Sparse LSM¶
Least squares gives every dye in the matrix some share of every event, so noise ends up as small abundances on dyes the cell does not carry. Sparse LSM puts the rules into the fit instead of tidying up after it. While it is chosen, two boxes take the place of WLSM Average Variance and Fast Poisson / NB solver:
| Control | Effect |
|---|---|
| Max Dyes | At most this many dyes in one event. 0 = no limit |
| Min Abundance | A dye is either exactly 0 or at least this, in the units of the result, which depend on Norm Spectra. 0 = no floor |
For each event it finds the best fit those rules allow, searching the combinations of dyes by branch and bound, the method a mixed-integer solver such as Gurobi uses, and proves it to within 0.01% of the objective. No such solver or licence is needed. Regularization and Penalty apply as on the other solvers. With both boxes at 0 it is Non Negative LSM.
- Its zeros stay zeros. The other solvers put small random values in place of their zeros; this one does not, as that would break its rules. Expect events piled up at exactly 0.
- ErrCount counts the events whose search stopped before the proof, after 20000 nodes. They keep the best solution found, which keeps the rules, and can be stepped through as usual.
- The rules are an assumption. Fitting a dye at its floor or leaving it out changes the answer, and a dim population under Min Abundance is gone. Check the settings on controls whose answer you know before trusting them on a sample.
Running it¶
Click Unmix. The window shows elapsed time, an ETA and an ErrCount - the number of events the solver could not fit. A non-zero error count on a well-conditioned panel usually points at a bad control rather than at the solver.
Unmix Current Cell solves a single event and shows the fit, which is the way to find out why a particular population is landing where it is.
Adding the results to the dataset¶
Click Add Unmixed Parameters. One new parameter is created per dye, holding that dye's
abundance for every event. Its $PnN and $PnS are what the unmixer's Save would
write - the analyte and the stain by default, or as
For FCS standard violators asks - and
it is listed as $PnN_$PnS, CD4_BV650. $PnN is unique among the dataset's parameters:
two controls of one analyte give CD4 and CD4-1, and a name a channel already has is
numbered rather than taken. Adding again under the same names replaces the earlier ones.
Set a Prefix first - it goes in front of $PnN - if you want them grouped together in
the parameter list, or want to keep two unmixing attempts side by side.
From here the unmixed parameters behave like any other: give them a BiExp scale, plot them on chart nodes, and gate.
Saving your work¶
- The Unmixer node keeps the Unmixer's whole configuration as the Unmixer was last closed - destinies, names, gates, bands and backgrounds - and the project saves it with the node: after reopening the project, Unmix brings every panel back as it was left. The parameters are the node's own, as Select Pars last set them.
- Save in the Unmixer stores the panel configuration in the data folder's
INFOfolder, so reopening the plate does not mean re-assigning every control. - Save in the matrix window writes the unmixed plate as FCS files, one per well, into a folder you pick: the parameters you choose to keep and the unmixed ones, named as described under Naming the controls.
- Export in the matrix window writes the mixing matrix as CSV.
- Add to DB puts the reference spectra in the spectrum collection for reuse.
The unmixed parameters are part of the loaded dataset, not of the saved project - see Derived parameters.