Using FlopR

Alex J H Fedorec 02/06/2021

• Prerequisite Knowledge
• Installation
• A Quick Note on .csv Files
• Plate Reader Calibration
• Processing Plate Reader Data
  • Autofluorescence normalisation details
• Flow Cytometry Processing
  • Process a single .fcs file
  • Process a folder of .fcs files

Prerequisite Knowledge

We have attempted to make our software usable with minimal prior knowledge of the R programming language or programming in general. You will need to be familiar with the idea of running commands from a console or writing basic scripts. For R beginners, this is a great starting point, there are some good resources here and we suggest using the RStudio application. It provides an environment for writing and running R code.

Installation

FlopR relies on several other R packages. Most of them are available through the “Comprehensive R Archive Network (CRAN)” which just means that they can be automatically installed. There are, however, a couple that need to be manually installed if you are using the flow cytometry processing functions. To do this use the following commands:

install.packages("devtools", repos = "https://cloud.r-project.org/")

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install(c("flowCore", "flowClust", "flowStats"))

Once those packages have been installed we are ready to install FlopR.

devtools::install_github("ucl-cssb/flopr")

This grabs the latest version of FlopR from GitHub and builds it on your computer. If it installed successfully we should now be able to load the FlopR package in R.

library(flopr)

The examples in this document can be run using the data in the “example” folder. Download the whole folder and make sure that you have set your current working directory (you can use the setwd() command in R) to the location where you saved it on your computer

A Quick Note on .csv Files

This package makes extensive use of .csv (comma separated variables) files for data and meta-data. Unfortunately, not all .csv are created equal.

• When using a Windows OS computer we recommend that you save your .csv files explicitly with a UTF-8 file encoding (as shown below). This means that your files can be used by someone running a different operating system without error.
• Some parts of the world use decimal commas instead of decimal points. In these places, .csv files use “;” as a separator instead of “,”. Unfortunately, we are unable to automatically detect which format your .csv files are in. As such, you will have to ensure that your files are saved using “,” as the separator and decimal points for the decimal mark. This article has some help for doing so.

Plate Reader Calibration

The experimental protocols for producing absorbance and fluorescence calibration data can be found here and here.

The data produced by plate readers from different manufacturers comes in different formats. The first step we need to do is to “parse” the data from the plate reader into a standard format. We have written an example parsers for use with data from Tecan plate readers and the Biotek Neo 2. If you need help writing a parser for your plate reader, please contact us and we’ll see what we can do.

For a Tecan plate reader, the data is saved as an Excel .xls file. As of flopR version 0.4.02, the spark_parse function accepts Excel files (.xls and .xlsx). If you are using an earlier version, the data first needs to be saved as a .csv file (open in Excel and “Save As” .csv) that can be read by R. We also need a .csv file telling us what is in each well of our microtitre plate. An example can be found in the “examples/plate_reader/tecan_spark” folder, but the first few rows looks like this:

<div class="kable-table">

| calibrant | fluorophore | media | concentration | replicate | well | |:------------|:------------|:------|--------------:|----------:|:-----| | fluorescein | GFP | PBS | 7.53000e+14 | 1 | A1 | | fluorescein | GFP | PBS | 3.76500e+14 | 1 | A2 | | fluorescein | GFP | PBS | 1.88250e+14 | 1 | A3 | | fluorescein | GFP | PBS | 9.41250e+13 | 1 | A4 | | fluorescein | GFP | PBS | 4.70625e+13 | 1 | A5 | | fluorescein | GFP | PBS | 2.35313e+13 | 1 | A6 |

</div>

Once we have the calibration data and layout .csv files we can parse the data.

flopr::spark_parse(data_csv = "examples/plate_reader/tecan_spark/191219_calibration_membrane.csv",
                   layout_csv = "examples/plate_reader/tecan_spark/calibration_plate_layout.csv",
                   timeseries = FALSE)

The data_csv argument takes the path to the calibration data. layout_csv is the path to the plate layout .csv file. Finally, the Tecan plate readers save timeseries data differently from single timepoint data, so we have a Boolean flag, timeseries, that lets the parser know that this is not a timeseries.

The spark_parse() function saves the parsed calibration data in a new .csv file, in the same location as the calibration data, with "_parsed" appended to the filename. The first few rows look like this:

<div class="kable-table">

| calibrant | fluorophore | media | concentration | replicate | well | OD600 | OD700 | GFP 40 | GFP 50 | GFP 60 | GFP 70 | GFP 80 | GFP 90 | GFP 100 | GFP 110 | GFP 120 | row | column | |:------------|:------------|:------|--------------:|----------:|:-----|-------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|--------:|--------:|--------:|:----|-------:| | fluorescein | GFP | PBS | 10.0000 | 1 | A1 | 0.0921 | 0.0831 | 1830 | 9811 | 36911 | NA | NA | NA | NA | NA | NA | A | 1 | | fluorescein | GFP | PBS | 5.0000 | 1 | A2 | 0.0942 | 0.0852 | 932 | 4993 | 19221 | 54510 | NA | NA | NA | NA | NA | A | 2 | | fluorescein | GFP | PBS | 2.5000 | 1 | A3 | 0.1015 | 0.0928 | 453 | 2434 | 9448 | 27864 | NA | NA | NA | NA | NA | A | 3 | | fluorescein | GFP | PBS | 1.2500 | 1 | A4 | 0.0985 | 0.0899 | 232 | 1253 | 4853 | 14513 | 36349 | NA | NA | NA | NA | A | 4 | | fluorescein | GFP | PBS | 0.6250 | 1 | A5 | 0.0957 | 0.0905 | 114 | 617 | 2404 | 7128 | 18282 | 41812 | NA | NA | NA | A | 5 | | fluorescein | GFP | PBS | 0.3125 | 1 | A6 | 0.1027 | 0.0965 | 54 | 294 | 1137 | 3388 | 8672 | 20095 | 42244 | NA | NA | A | 6 |

</div>

The parser has extracted the information we need from the calibration data and merged it with the plate layout information so that we now have columns containing each of the measurements for each well.

Now we can actually calculate our calibration coefficients. To do this we just need to use one function and give it our parsed data.

flopr::generate_cfs(calibration_csv = "examples/plate_reader/tecan_spark/191219_calibration_membrane_parsed.csv")

For details about how this process works, you can read our paper here. At the end, there should be two .pdf images showing the calibration curves for absorbance and fluorescence, along with a new .csv file, appended with "_cfs", containing the parameters for use in the future, the first few rows of which look like this:

<div class="kable-table">

| cf | beta | calibrant | fluorophore | measure | |-----------:|-----------:|:------------|:------------|:--------| | 184.7274 | 0.0057476 | fluorescein | GFP | GFP 40 | | 996.4472 | -0.0035424 | fluorescein | GFP | GFP 50 | | 3821.0497 | -0.0004737 | fluorescein | GFP | GFP 60 | | 11298.9531 | 0.0002015 | fluorescein | GFP | GFP 70 | | 29128.3783 | -0.0007481 | fluorescein | GFP | GFP 80 | | 65834.9342 | 0.0012751 | fluorescein | GFP | GFP 90 |

</div>

The “cf” column contains the calibration coefficients that will be used to calibrate our data in later experiments.

Before we get too excited we need to check the images to make sure that the calibration curves look sensible. The software attempts to remove data points which it deems are invalid, but this process isn’t perfect and occasionally may need you to remove data points from the "*_parsed.csv" file. Using the example data, you can see (here) that some of the fluorescein wells are considered valid absorbance measurements. In this case, it isn’t the end of the world since we would never use the parameters produced from those two curves.

n.b. Currently the software is setup to work with “microspheres” for calibrating cell number and “fluorescein” for calibrating GFP fluorescence. We hope to extend it in the near future to work with o