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.

Editing 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 can edit the the bounding gates yourself if they are not adequate. Depending on your settings, changing the bounding gates will do one of two things:

• Auto - Everytime a bounding gate is changed, the autospill algorithm will rerun and will automatially update. This can be easier but if you have a slower computer, it can cause some lag.
• Manual - When a bounding gate is changed, the autospill matrix will turn red in the file tree, signifying that it is out of date. You can manually update it and apply the bounding gate changes to the matrix by right clicking on the autospill pipeline and selecting "Update Autospill".

You can switch between these two settings by going to "Settings"->"Compensation" in the main menu.

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.