Debarcoding FCS Files - nolanlab/single-cell-debarcoder GitHub Wiki
Prepare your barcode key before opening the Debarcoder. The barcode key is a spreadsheet that lists the masses of the barcode metals, the names of the barcode populations, and their corresponding binary key. A sample that demonstrates the format is available here. When writing your key, keep in mind that the labels in the key will be used to name the final debarcoded FCS files.
Important notes on the formatting of the barcode key:
- The barcode key must be saved as .csv. You can do this in Excel by making a spreadsheet and then choosing "Save As ..." and then selecting .csv in the "Format" menu.
- Certain types of Excel formatting will cause problems even after being saved as .csv. To avoid this, if you're copying and pasting from an existing spreadsheet, use "pastespecial > values."
- It is okay to include rows corresponding to barcode combinations you did not use, as long as every metal in your key is used for at least one sample. Similarly, it is best that all metals are both positive and negative somewhere in your key.
- Do not leave the top left cell of the key empty.
A sample barcoded FCS file whose barcode scheme corresponds to the sample key is available for download here.
Upon opening the debarcoder, you will be prompted to select a barcode key. Once the main application window has opened, click on the 'Select FCS File' button to load your data. If at any point you edit your barcode key, you will need to re-load it into the debarcoder with the 'Change Key' button in order for that edit to take effect.
There are two user-adjustable parameters that contribute to the barcode deconvolution.
This number defines the minimum distance required between the "positive" and "negative" barcode channels on an individual cell in order for that cell to be assigned to a barcode, rather than discarded. The barcode intensities are rescaled such that the separations fall between 0 and 1. Below, the barcode intensities and separations are plotted for six rows of an FCS file. Note that Event 2 is likely debris since all barcode channels are low, and Event 6 is likely a doublet since more than 3 barcode channels are high; this is reflected in their low separation values. A separation cutoff of 0.3, for example, would keep cells 1, 3, 4, & 5 but discard events 2 & 6.
After initial barcode assignment, the barcode populations can be trimmed based on Mahalanobis distance to exclude the outliers in each population. Below four biaxial plots of barcode 111000 are shown, and the cells are colored by Mahalanobis distance. For example, to exclude the red and orange cells, one would set the Mahalanobis threshold to 40. Note that Mahalanobis distances (and therefore the colors) are calculated based on all of the barcoding channels, but each plot only shows two of those channels at a time.
When you select an FCS file, a preliminary debarcoding is performed over a range of separation parameters. This may take a few moments. When it is finished, the panel on the right will display a histogram of total event counts binned by barcode separation.
Below this will be a plot of the yield for each barcode population as a function of separation cutoff. Clicking on any line in the plot will cause the label from the barcode key corresponding to that population to be displayed.
Use the yield profile from the preliminary debarcoding to enter an initial minimum separation cutoff. The goal is to filter out uncertain barcode assignments but still retain sufficiently large barcode populations; this is typically a value just below which the cell count of the barcode populations dramatically decreases. In the example shown here that would be a separation cutoff of 0.4-0.5. You may navigate back to this summary plot at any time by selecting the 'Separation' plot type.
Evaluate the minimum separation cutoff and Mahalanobis threshold by browsing through the 'Event' plots of different barcode populations. Both the raw intensities on an arcsinh scale and their re-scaled values are shown, and should look very similar. Only events whose separations and distances meet the filtering criteria will be shown. It may be useful to use the zoom and pan tools to get a closer look. You can zoom in to a particular area by dragging a box around it.
After zooming, you can scroll through the events by dragging with the pan tool.
Adjust the cutoffs if necessary, settling on the values for which all populations consist of cells in which positive and negative barcodes are well-separated, but without excluding more events than necessary. In contrast to the well-separated data above, below is what the 'Event' plot may look like if a too-lenient separation cutoff is chosen. By zooming in one can see there are numerous suspected doublets.
The 'Single Biaxial' option creates a scatter plot of two barcode parameters of a single barcode population colored by either Mahalanobis distance or separation cutoff. The example below shows a plot of BC3 x BC4, which in population 110010 should both be negative. The separation cutoff is set at 0.3 and the Mahalanobis threshold is 30.
Reducing the Mahalanobis threshold to 15 removes the blue events, and then adjusts the color scale to the new range.
The process of adjusting the separation cutoff and Mahalanobis threshold may be iterative.
A snapshot of all biaxial plots is also available via the 'All BC Biaxials' button.
While browsing through the Event and Biaxial plots, at top of the figure is a bar graph that displays the total cell yield for each barcode population with the currently selected filtering parameters. The plot will automatically update when the filtering parameters are changed.
Create a separate FCS file for each barcode population by pressing the Save Debarcoded Files button, which will give a prompt to select the folder in which to save the files. The files will be named by appending the entries in the barcode key to the base file name written next to the ‘Save Debarcoded Files’ button. There will also be an FCS file created of the events that are left unassigned to any barcode population.