Skip to content

FlowSOM

A FlowSOM node clusters the events feeding it with FlowSOM (Van Gassen et al., Cytometry A, 2015), following the workflow of Quintelier et al., Nature Protocols, 2021. It covers the whole workflow, from training the map to comparing groups of wells:

  1. it trains a self-organising map on the events reaching it, an equal number from every well;
  2. it links the map's nodes into a minimum spanning tree and groups them into metaclusters;
  3. it lets you check and name the metaclusters, merge or split them, and compare them with your manual gates;
  4. it counts each well's events in every cluster, takes their median intensities, and compares two groups of wells.

Create one with FlowSOM on the project panel toolbar, and feed it from the population you want clustered. Nothing runs until you press Start.

Before you start

FlowSOM is only as good as the events you give it, and most problems start here:

  • Compensate or unmix the data first (Compensation, Spectral unmixing).
  • Transform every marker you cluster on with a sensible scale: logicle or arcsinh for flow, arcsinh with cofactor 5 for mass cytometry (Parameters and scales). The node uses each marker through the scale it is plotted with, put on 0..1 over that scale's range, the way the embedding node does. It applies no further scaling.
  • Clean the acquisitions: a PeacoQC node at the start of the graph rejects the stretches of a run a clog or a change of flow disturbed, and can remove margin events and doublets too. Gate on from its PQC good.
  • Gate out debris, doublets and dead cells upstream, and feed the node from that gate. Only the events reaching the node, in the wells switched on, are clustered.
  • Look for batch effects before trusting the clusters. If clusters split by acquisition day rather than by biology, normalise first. The node has no normalisation of its own.

Running it

Markers picks the markers to cluster on. Use lineage and phenotype markers. Leave out the functional or state markers you want to compare between groups afterwards; you can still read their medians on the Samples tab. The pick is remembered for the next FlowSOM node on the same plate.

Start asks for:

Field Default Meaning
Parameter name FlowSOM The node writes <name>-node and <name>-meta, each event's map node and metacluster
Grid width, Grid height 10, 10 The map: 100 nodes. It over-clusters on purpose; use a larger grid (15 x 15) to find rare populations
Metaclusters 10 Pick a few more than the populations you expect, then merge
Training events 100,000 Taken in equal numbers from every well, so no sample dominates the training (all of a well that has fewer)
Passes over them 10 How many times the map sees the training events
Seed 42 The same seed, events and settings give the same map, bit for bit

Training runs on a thread of its own, with a progress window; Stop (or Cancel in the window) abandons it. Afterwards every event of the data goes to its nearest map node, so the node's other tabs, its gates and its two parameters cover all the events, not only the training sample.

The map is saved with the project. Opened on other data, the node places that data's events on the same map, provided the data has the same markers.

Over-cluster, then merge

Results change with the seed and the grid size. Asking for somewhat more metaclusters than you expect and merging the ones that turn out to be the same works better than aiming for the exact number.

Tree

The minimum spanning tree of the map's nodes. Each node is a disc whose area follows its share of the events reaching the node, over a halo in its metacluster's colour, and the metaclusters' numbers sit at their centres. Colour picks what the discs show:

  • Stars - the markers: a ray per marker, as long as the node's value of it, each marker from its lowest node to its highest (FlowSOM's star plot)
  • Metaclusters: the metacluster's colour
  • Manual gates: a pie of the manual gates its events are in
  • any parameter: the node's median of it, dark (low) to yellow (high). This includes markers the map was not trained on.

Click a node to pick its metacluster. The line above the tree shows the node's and the metacluster's event counts, and the metacluster is outlined, in the tree and on the heatmap.

Heatmap

Each metacluster's median of every marker, over the events reaching the node (a random 200,000 of them on bigger data). Each marker is coloured from its lowest metacluster (dark) to its highest (yellow). The share of the input in each metacluster is on the right. Read it to name the metaclusters.

Metaclusters

One row per metacluster: its number, its name, its map nodes, its events and their share of the input. Pick a row, or a node in the tree, then:

  • Rename - name it after its phenotype (CD4 T cells). Its gate takes the name.
  • Merge - merge it into another metacluster you choose from a list. If it had a gate and the other has none, the gate moves to the other. Otherwise the gate is deleted.
  • Split - split its nodes in two by average linkage of their profiles, the clustering FlowSOM's metaclustering uses. One half gets a new number.
  • Gates - pick the metaclusters to become gates of the node.

Metacluster gates

Each metacluster gate is a population of the node, like a gate drawn on a chart. Link it to other nodes to gate further, or to an embedding node to see the metaclusters on a tSNE or UMAP. The events take the gates' colours everywhere, like any other gate's. The gates follow merges, splits and renames, and they are saved with the project.

The parameters <name>-node and <name>-meta do the same job in a plain chart: plot <name>-meta as a histogram and gate on it.

Samples

The per-sample analysis, with each well as a sample. One row per well that sends events to the node, and one column per metacluster, or per map node with Map nodes. The first box picks what the cells show:

  • % of the well - the well's events in each cluster, as a share of the well's events reaching the node
  • Events - the counts
  • Median of - the median of the parameter picked next to it, in the parameter's own linear units. Use any parameter, including the functional markers you left out of the clustering.

Groups names two groups and asks which wells belong to each. Once both groups have wells, five rows appear under the wells:

Row Meaning
Median (first group) The group's median of the column
Median (second group) The other group's median
log2 fold log2 of the second median over the first
p Two-sided Wilcoxon rank-sum test of the column between the groups, computed as R's wilcox.test: exact for groups under 50 wells without tied values, otherwise the normal approximation with continuity correction
q The p values adjusted for the number of columns tested (Benjamini-Hochberg, as R's p.adjust)

With % of the well this tests differential abundance: whether a cluster is more common in one group. With Median of a marker it tests differential state: whether the marker's expression within a cluster differs between the groups. The Wilcoxon test suits simple two-group designs. For covariates or paired samples, export the table and use a dedicated tool (diffcyt).

Export CSV saves the table, statistics included, with full-precision numbers.

Gates

How well the metaclusters reproduce your manual gating. Every gate in the project that holds part of the events reaching the node, but not almost all of them, is listed. A gate the input comes through holds all of them and tells nothing. Manual gates picks which gates to compare with. For each gate:

Column Meaning
Events here The gate's events among those reaching the node
Best metacluster The metacluster with the highest F1 against the gate
Precision % How much of that metacluster is the gate's population
Recall % How much of the gate's population that metacluster holds
F1 The two combined. Above 0.9 is a close match

The line above the table gives the weighted F1, the F1s averaged by gate size (FlowCAP's F-measure), and the purity. Purity is the share of gated events whose metacluster's most common gate is their own. Each event counts in the smallest of the listed gates holding it, its most specific population. The same assignment draws the pies of the tree's Manual gates colouring.

A low F1 for one population usually means its events are split over two metaclusters (merge them), or share one with a neighbour (split it, or use a larger grid).