Documentation

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 does a pretty good job of matching parameters and control files, but it may require some manual adjustment. Once all the parameters/files are selected and matched, hit "Apply" to begin the calculating the matrix. It may take a few moments, depending on how fast you computer is, how many parameters you are compensating, and how many events are in the file, Once the calculation is completed, compensated populations will appear in the file tree for all files in the current project.

Additionally, after calculating a matrix, an "AutoSpill" gate will appear for all control files, showing the FSC vs SSC gate that was used in the algorithm. Again, Floreada does a decent job a selecting an appropriate population to use for the calculation, but you may need to make adjustments. If you do want to make changes, just adjust the "AutoSpill" gate manually and rerun the compensation algorithm exactly as before.

In-File Compensation

Some FCS files contain a precomputed spillover matrix. According to the lastest 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 double click it in the file tree. 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:

Detector
FluorochromeFITCPE
FITC1.00.1
PE0.031.0

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 "Comp" will show compensated events. Similarly, all gates or stats applied with just the file selected, will be uncompensated. All gates or stats applied with "Comp" selected will be on compensated events. This may also facilitate adjusting compensation values manually.

Delete Compensation

A compensation matrix can be deleted by right clicking on it in the "Projects" sidebar then clicking "Delete". Doing so removes all sub-gates and stats. This can not be undone.

Edit Compensation

Double clicking a compensation matrix with reopen the matrix menu and allow you to edit it.

Copy Compensation

Compensation can be dragged and dropped on other files. Please note that unlike gates, compensation matrices that are copied are not linked and changes to one will not change a copied matrix' values. Also since files can only have one matrix, if you drag to a file that already has one, you will overwrite its current matrix.

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.