Phenotyping¶
A phenotyping node sorts the events feeding it by how bright each marker is, lists the phenotypes - the combinations of levels - those events make, and names the cells of the CD database each phenotype could be. Checking phenotypes makes them the node's gate, a population like any other.
Create one with Phenotype on the project panel toolbar, and feed it from the population you want described - live single cells, or a CD45+ gate. Like any node it sees every event when nothing is linked to it.
The node has two sides. On the left, Markers - the levels of each marker - and Cells, the lineage of the CD database. On the right, Phenotypes, Samples and Histogram, with the node's controls and a status line along the bottom.
Before you start¶
- Compensate or unmix first (Compensation, Spectral unmixing). Levels read off raw spillover mean nothing.
- Give each marker a sensible scale - BiExp for compensated or unmixed fluorescence (Parameters and scales). The levels are found on the histogram as it is plotted.
- Name the parameters after their markers. The node looks each one up in the CD database by its names: an unmixed parameter named after its control, CD4_BV650, is found as CD4. A parameter the database does not know still takes part in the phenotypes; it just names no cell.
Picking the markers¶
A new node takes the markers last picked on this plate. The first time, it takes every
parameter the CD database knows as a marker, up to 32. Click the ribbon's axis to pick
them again: the picker lists the parameters, and the pick is remembered for the next
phenotyping node on the same plate (INFO\Pheno_Pars.ini).
A node whose markers the data does not have yet - a project opened before its unmixing - keeps them and waits: nothing is drawn, its gate passes no event, and the ribbon's title names what is missing. As soon as Add Unmixed Parameters puts those parameters in, the node fills in by itself, with its thresholds and its checked phenotypes as they were saved. Picking the markers again is what drops one.
Levels¶
The Markers tab is a ribbon, one bar per marker: the marker's histogram over the events reaching the node, cut into levels drawn in their own colours - - blue, + gold, ++ orange, +++ red.
A marker's levels are its positive peaks. The brightest peak is +++, the one below it ++, a third +; everything below the first threshold is -. So a marker with one positive peak has the levels - and +++, one with two -, ++ and +++, and one with three all four. The peaks are found from the data: the histogram is smoothed until its peaks settle, two peaks count as one population unless a deep enough valley parts them, a peak holding under 1% of the events is no peak, and the lowest peak is the negative one when it lies within three robust SDs of zero.
up to 3 peaks - the box at the bottom - is the most positive peaks a marker is looked for: 1, 2 or 3.
Correcting the levels¶
| Action | Result |
|---|---|
| Drag an edge of a level on the ribbon | Move that threshold |
| Click a marker's bar | Show its histogram on the Histogram tab, the thresholds as cursors to drag |
| Right-click a bar, or the histogram | Add a peak here, Delete this peak (its events join the level below), or Find the peaks again for that marker |
A marker you have corrected by hand keeps its peaks when the data changes upstream; the others follow the data. Auto finds every marker's peaks and thresholds again, the corrected ones too - when some were set by hand it names them and asks first, No being the default.
Gates makes each level a gate of its own, placed about its peak the way the SSM node places its gates, instead of a band that runs from one threshold to the next. Dragging a gate's edge moves only that gate. An event outside every gate of a marker belongs to no level of it, so it is left out of every phenotype and out of the node's gate: the status line counts those events, and the Histogram tab's title gives each gate's share and the share outside them.
Lock keeps every marker's peaks and thresholds where they are: no change upstream, no other plate, neither the peaks box nor Auto moves them (both are off while locked). Dragging still does. A project saved locked cuts the next plate exactly as it cut this one - the way to apply one set of thresholds across experiments.
Phenotypes¶
The Phenotypes tab is a table with a row per marker and a column per phenotype: every combination of levels found among the events reaching the node, the most frequent first. The bar above a column is its share of the events; the number below it is how many cells of the CD database it could be. The table shows the 400 most frequent phenotypes, and the status line says how many rarer ones are left out.
Hover over a column and the status line spells it out - the phenotype (CD3+++ CD4++
CD8-), its events and share, and the cells it could be, each with how many of the
phenotype's positive markers it matches out of the markers the database gives it a level
for (CD4 T 3/3).
Click a column to check it. The node's gate - its output pin - is the events of the checked phenotypes. All checks every phenotype in the table, None none.
How cells are matched¶
A cell of the CD database matches a phenotype when no marker rules it out. A level the database does not give for that cell rules it neither in nor out, and a cell with a level for none of the phenotype's markers is no match at all. The matches come ranked by the phenotype's positive markers they match - a matched negative says less, most cells being negative for most markers - then by how many of its markers they have a level for.
Exact levels tells +, ++ and +++ apart when looking phenotypes up; without it any positive level matches any positive.
The marker of a row¶
Click a row and its CD marker appears in the Marker box above the table. Type there to change it - the box suggests the database's markers by any of their names. The button beside it reads None for a parameter with a marker, and takes the marker away (the parameter is no marker of the database); for one without, it reads Find and looks the marker up by the parameter's names again.
Cells¶
The Cells tab, beside Markers, draws the CD database's lineage with the cells of the checked phenotypes highlighted, so the cells and the table are seen together. It follows the checks as you make them.
Double-click the splitter between the two sides to hide the right-hand one.
Samples¶
The Samples tab compares the wells. It has a row per phenotype - those checked, or every one in the table when none is - and a column per well whose events reach the node, with each well's file, group and event count above the phenotypes. Every well is cut by the same thresholds, placed on all the wells together.
The first box picks what the cells show:
| Choice | Each cell |
|---|---|
| % of the well | The well's events of that phenotype, as a share of the well's events reaching the node |
| Events | The count |
| Change from baseline | The share less the baseline well's, in percentage points |
| log2 fold from baseline | log2 of the share over the baseline well's |
The baseline well is picked in the box beside it.
Groups names two groups of wells - the first is the reference - and asks which wells belong to each. Once both have wells, five columns appear before the wells: each group's median, the second group's log2 fold over the first's (in the two change modes, the difference), and each phenotype's two-sided Wilcoxon rank-sum p with its Benjamini-Hochberg q, computed as the FlowSOM node does.
Export CSV saves the table as it is shown.
Saving¶
The project keeps the node's markers, each marker's peaks, thresholds and gates, the boxes, the lock, the checked phenotypes, and the Samples tab's choices and groups. The node's gate is stored like any other and links up again when the project loads.