Compensation

Create Compensation

AutoSpill

Floreada.io implements automatic compensation using the AutoSpill algorithm. AutoSpill is a novel method for calculating a compensation matrix developed by Dr. Carlos Roca. It has several advantages that make it easier to implement and easier to use compared with traditional compensation, including that the user does not need to select positive and negative populations. You can read more about AutoSpill here. If you do use AutoSpill Compensation, we would encourage you to cite that manuscript.

To create a new compensation matrix, click the Compensation button from the side panel. In the compensation menu, select all parameters you would like to include and match the parameter to the appropriate single-stained control file. Floreada will automatically try to choose the best file for the parameter you select. Once all the parameters/files are selected and matched, hit "Apply" to begin the calculating the matrix. The time to process varies depending on how fast your computer is, how many parameters you are compensating, and how many events are in the file. Once the calculation is completed, compensated populations named "Autospill" will appear in the file tree for all the relevant files.

Additionally, after calculating a matrix, an "AutospillBounds" gate will appear for all control files, showing the FSC vs SSC gate that was used in the algorithm.

Custom AutospillBounds Gate

Sometimes generated AutospillBounds gates are poor and includes only a few events. This can throw off the quality of the calculated matrix. You may want to instead use a custom bounding gate. When the Autospill algorithm runs, it will look for a gate named "AutospillBounds" on all of the relevant files. If a gate with that name exists, it will use it as the bounding gate. If it does not exist, it will generate a new bounding gate. So to provide your own bounding gate, create a new gate on the file with the name "AutospillBounds"

Similarly if you run the algorithm and it auto-generates a poor bounding gate, you can edit the bounding gates and then re-run autospill, which will then use your edited gate.

In-File Compensation

Some FCS files contain a precomputed spillover matrix. According to the latest FCS spec, this matrix is specified in the "$SPILLOVER" keyword. If an FCS file contains this keyword, it will be automatically added as compensation for the file.

Additionally there are some additional unofficial keywords to specify compensation matrices, which companies used prior to an official keyword being fully specified. The "SPILL" keyword is similar in structure to the official spec and will likely work ok. Other compensation keywords will be ignored.

Viewing a Spillover Matrix

To view a spillover matrix, you can right click on it in the file tree and click "Details". The table in the compensation menu is represented as defined in the FCS specification. An example spillover matrix from the FCS3.1 specification and its interpretation is shown below:

Table 1: Spillover matrix specifying a 2-way compensation between "FITC" and "PE" parameters, with a spillover of 10% from FITC to PE and 3% from PE to FITC. - FCS3.1 Specification pg.26

Apply Compensation

Once a compensation matrix is created for a file, it will be placed under the file in the file tree. You can easily switch back and forth between applying and unapplying compensation to a file. Selecting the file alone will show uncompensated events, selecting "FCSComp" will show compensated events. Similarly, all gates or stats applied with just the file selected, will be uncompensated. All gates or stats applied with "FCSComp" selected will be on compensated events. This may also facilitate adjusting compensation values manually.

Edit Compensation

Right clicking a compensation matrix in the file tree and clicking "Details" will open a view of the matrix and allow you to manually edit it.

AutoSpill Implementation Details

This section is for informational purposes for those interested in the topic.

The reference implementation of AutoSpill is written in R and is available under the MIT license with source code on GitHub. There is also a server-side web app provided by the AutoSpill team here. One of the main philosophies of Floreada is to do all processing client side, without utilizing 3rd party libraries, so we ended up implementing the algorithm outlined in the manuscript from scratch in TypeScript, including utilities such as the robust linear model that algorithm depends on.

There are a few minor differences between the reference implementation and our implementation. The first noticable difference is how we select a size gate to select cells for use in the calculation. The AutoSpill manuscript outlines a multiple step process for selecting an appropriate size gate automatically. We used a simpler method (only 1 tessellation) which works well on most (but not all) files. Additionally we allow the user to adjust the gate and select whatever size criteria they would like.

A second difference is the robust linear model (RLM). An RLM is similar to a standard linear regression, but lessens the contribution of outliers. There are several well known algorithms for performing an RLM. The AutoSpill manuscript does not specify which RLM to use, but the reference implementation in R utilizes an RLM library (MASS) that uses the "Huber" RLM by default, so we wrote a Huber implementation in TypeScript to use. There are several parameters in the Huber algorithm that can be tuned, resulting in different results from the model. Therefore, although the results will be quite close between the two implementation, they will not be identical.