Embedding node¶
An embedding node is a chart node that embeds the events feeding it in two dimensions - by tSNE, UMAP, an autoencoder, PCA or FlowSOM - and gives every event of the data a place in that embedding. The coordinates become two parameters, so the node's own chart plots them and you gate on them as on any other chart.
It does on a population what the Embedding chart tab does on the whole dataset (see Dimensionality reduction, which describes the methods and their settings in full): gate down to the cells you care about first, link that gate to the node, and the embedding spends its resolution on them rather than on debris.
Create one with Embedding on the project panel toolbar.
The menu¶
Along the top of the node:
| Control | Effect |
|---|---|
| Method box | Autoencoder, tSNE, UMAP, PCA or FlowSOM |
| Model box | A saved model of that method, applied instead of running one - see below |
| Select Pars | The parameters to embed. A new node offers those last picked on this plate, or else those checked for tSNE on the Embedding tab |
| Start | Run the method on the events reaching the node. It reads Stop while a run goes on |
| Save Map | Keep the node's model with the saved ones, to apply it to other data |
Below the menu is an ordinary chart node: axes, gates, gate grid and floating toolbar.
Running it¶
Start takes the events reaching the node, in the wells switched on, and the parameters picked with Select Pars - at least three. Each parameter goes in through the scale it is plotted with, set to 0..1 over that scale's range, as on the Embedding tab. Only one embedding or training runs at a time, in the node or on the tab; the progress window shows it, and Stop abandons it.
Each method first asks for the parameter name - the coordinates are name-1 and
name-2 - together with its own settings:
| Method | Asks for | What it does with the node's events |
|---|---|---|
| tSNE | The name | Runs on them; then asks about a map (below) |
| UMAP | The UMAP dialog: name and settings | Runs on them; then asks about a map |
| Autoencoder | The training dialog | Trains on them and embeds every event of the data |
| PCA | The name | Fits the components on them and applies that transform to every event |
| FlowSOM | Name, grid width and height, metaclusters | Trains the map on them; every event goes to its nearest map node |
Running the same method again writes over the node's own coordinates; anything else gets a name no parameter has yet.
tSNE and UMAP: the map¶
tSNE and UMAP place only the events they are given. When a run ends its events go on the chart where it put them, and the node asks whether to train a map as well - a small network that learns the layout from the parameters, as Train Map on the Embedding tab does (see Mapping other data):
- Yes trains it, keeping some of the events back to measure how well it follows the layout. The map then places every other event of this data, and of any other data the node is opened on, and Save Map can keep it. The run's own events keep the coordinates the run gave them.
- No keeps the run as it is. Every event the run did not place is put aside at one spot, below and to the left of the layout, so it is easy to leave out of a gate. There is no map to save, and other data is not placed - the log says to run the method again.
The map trains with the epochs and batch size last used for Train Map, on the graphics card when Use GPU for Autoencoder is on.
FlowSOM¶
With FlowSOM the chart shows the map's minimum spanning tree, each map node a disc of
its events, and two more parameters say where each event went: name-node, its map
node, and name-meta, its metacluster - plot either as a histogram to gate on it. For
the whole FlowSOM workflow - naming, merging and splitting metaclusters, comparing them
with your gates and across wells - use the FlowSOM node.
Gating on it¶
The node's chart plots name-1 against name-2. Draw gates on it as on any chart
node; they are ordinary gates, with output pins, that work on every event. Link the
node's gates onward, or plot the same two parameters on other chart nodes.
Measure on real parameters
As on the Embedding tab, cluster sizes and the distances between them on a tSNE or UMAP layout mean nothing. Use the embedding to find populations, then quantify them on axes that mean something.
Saved models¶
A node's autoencoder, or the map of its tSNE or UMAP run, is its own. Save Map copies
it into the saved models of the data that is open - its INFO\models folder, shared with
the Embedding tab (see Where models are kept):
- a model saved already, under any name, is not saved a second time;
- a name a saved model of the method has is asked about: Yes replaces that model, No asks again with a free name offered (tSNE2), Cancel saves nothing.
PCA and FlowSOM have no network to save: the node keeps their transform or map, and the project saves it with the node.
Picking a model in the model box applies it to the data - no run - provided the data has every parameter it was trained on; otherwise a message names the missing ones and nothing changes.
Saved with the project¶
The node keeps what it needs to show its embedding again: the method, the name, the parameters, the model, the PCA transform or the FlowSOM map, and for tSNE and UMAP the coordinates the run gave its events. Opened on the same data, the embedding comes back as it was. On other data - or once the values have changed - the model or map places every event; a tSNE or UMAP run without a map places none.
A node from an older project, saved when the coordinates were named with _, keeps naming
them name_1 and name_2, so the gates downstream still find them; it switches to -
once it writes under a new name.