Get Started • flowdex

Installation

Install release version from CRAN via

install.packages("flowdex")

Or download from github:

library(devtools) 
install_github(repo="bpollner/flowdex", ref="main")

Initialize Settings File System

Package flowdex makes use of the dynamic settings file system provided by package uniset. This has to be initialised just once by calling

library(flowdex)
flowdex::setup_settings(path.expand("~"))
#> The folder 
#> '/Users/bernhard/flowdex_SH' 
#> already existed.
#> The file 'flowdex_settings.R' already existed in 
#> '/Users/bernhard/flowdex_SH'
#> The variable 'flowdex_SH' already existed in the .Renviron file 
#> '/Users/bernhard/.Renviron'
#> 
#> The value of 'flowdex_SH' was correctly set to 
#> '/Users/bernhard/flowdex_SH'.
#> 
#> Setup successful

Follow the on-screen instructions and possibly re-start R.
From now on, various global settings and default values used by flowdex can conveniently be viewed and changed in the file flowdex_settings.R residing at

path.expand("~")
#> [1] "/Users/bernhard"

Download Tutorial Dataset

In order to walk the user over the main-features of package flowdex, a small tutorial-dataset has been created, along with gating strategy files and the required polygon-gate definitions.
Also, the workflow how to create the gating strategy file and the polygon gate definitions will be explained.

First, download the tutorial data from its Github repository:

library(flowdex)
src <- "https://github.com/bpollner/data/raw/main/flowdex_tutorial/flowdex_tutorial.zip"
td <- tempdir()
# this is downloading and unzipping the tutorial data if not already present:
flowdex::check_download_data(where = td, data_source = src, dsname = "flowdex_tutorial")
#> Download ok

Note: Description of Tutorial Dataset

All samples are tap water samples stained with cybergreen following the method as described in:
Prest, E. I., Hammes, F., Kotzsch, S., van Loosdrecht, M. C., & Vrouwenvelder, J. S. (2013). Monitoring microbiological changes in drinking water systems using a fast and reproducible flow cytometric method. Water Research, 47(19), 7131-7142 https://doi.org/10.1016/j.watres.2013.07.051
It was the purpose of the experiment to monitor the number of autochthonous bacteria in the water samples and their fluorescence distribution (LNA vs. HNA bacteria) over time.
A sample-ID string has been provided at the time of data acquisition, providing class and numerical variables describing each sample as described below.
There are two groups, experiment and control. The experiment group is denoted as ‘GPos’, the control group is denoted as ‘GNeg’.
From each group, 24 samples were taken each day, from which 18 samples are included In this dataset.
fcs files from day 4, day 5 and day 6 are included (denoted as T4, T5, and T6).
The 18 samples per day from each group are further structured in ‘thirds’ and beaker number: th1, th2 and th3 for the first, second and third third of the 18 samples, b1, b2, … up to b6 for the 6 samples (b for beaker) within each third.

Quickstart

After having (only once) set up the settings file system and having downloaded the tutorial dataset, you could dive straight in – for a quickstart to immediately see what flowdex can do, call:

library(flowdex)
setwd(paste0(td, "/flowdex_tutorial"))
fdmat <- flowdexit() # this might take a few seconds
#> Reading in fcs files... ok. 
#> Producing gating set... Applying fjbiexp transformation... ok. 
#> Gating: (1 gate)
#> done!
#> DNA+: Extracting binned data on FITC.A (res=220) and recalc. to volume... ok. 
#> Exporting data (1 gate) to xlsx...ok. 
#> fdmat-object saved.
fdmat@pData[1:5,] # to inspect volume and sample ID data
#>                                                                             sampleId
#> N_na_GNeg_T4_th1_b1.fcs tr: GNeg; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b1
#> N_na_GNeg_T4_th1_b2.fcs tr: GNeg; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b2
#> N_na_GNeg_T4_th1_b3.fcs tr: GNeg; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b3
#> N_na_GNeg_T4_th1_b4.fcs tr: GNeg; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b4
#> N_na_GNeg_T4_th1_b5.fcs tr: GNeg; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b5
#>                                            name     btim volume
#> N_na_GNeg_T4_th1_b1.fcs N_na_GNeg_T4_th1_b1.fcs 14:14:27  45500
#> N_na_GNeg_T4_th1_b2.fcs N_na_GNeg_T4_th1_b2.fcs 14:16:12  45500
#> N_na_GNeg_T4_th1_b3.fcs N_na_GNeg_T4_th1_b3.fcs 14:17:52  45500
#> N_na_GNeg_T4_th1_b4.fcs N_na_GNeg_T4_th1_b4.fcs 14:19:30  45500
#> N_na_GNeg_T4_th1_b5.fcs N_na_GNeg_T4_th1_b5.fcs 14:22:30  45500
fdmat@cyTags[1:5,] # to inspect class- and numerical variables assigned to each sample
#>                         C_treatment Y_Time.d C_waterType C_addedPA C_third
#> N_na_GNeg_T4_th1_b1.fcs        GNeg        4       nativ        no     th1
#> N_na_GNeg_T4_th1_b2.fcs        GNeg        4       nativ        no     th1
#> N_na_GNeg_T4_th1_b3.fcs        GNeg        4       nativ        no     th1
#> N_na_GNeg_T4_th1_b4.fcs        GNeg        4       nativ        no     th1
#> N_na_GNeg_T4_th1_b5.fcs        GNeg        4       nativ        no     th1
#>                         C_half C_beaker
#> N_na_GNeg_T4_th1_b1.fcs    ha1       b1
#> N_na_GNeg_T4_th1_b2.fcs    ha1       b2
#> N_na_GNeg_T4_th1_b3.fcs    ha1       b3
#> N_na_GNeg_T4_th1_b4.fcs    ha1       b4
#> N_na_GNeg_T4_th1_b5.fcs    ha1       b5
fdist <- fdmat[[1]] # to inspect fluorescence distribution
fdist[1:5, 130:134] # pick some random fluorescence intensities
#>                                flsc2876 flsc2889 flsc2901 flsc2914  flsc2926
#> N_na_GNeg_T4_th1_b1.fcs|DNA+ 14.1397064 6.147698 0.000000 0.000000 1.8443095
#> N_na_GNeg_T4_th1_b2.fcs|DNA+  0.0000000 0.000000 0.000000 0.000000 0.0000000
#> N_na_GNeg_T4_th1_b3.fcs|DNA+  0.9221548 0.000000 0.000000 3.073849 6.1476985
#> N_na_GNeg_T4_th1_b4.fcs|DNA+  6.1476985 3.073849 0.000000 0.000000 0.9221548
#> N_na_GNeg_T4_th1_b5.fcs|DNA+  6.1476985 7.326007 6.147698 3.073849 0.0000000

Look at ‘flowdexTutorial/rawdata/flscData_gateStrat.xlsx.xlsx’ to see the fluorescence distribution exported to file, observe the various sheets there.

Prepare Folder Structure

Take it step by step, not interested in the quickstart above: We assume that data from a single experiment will be residing in a single folder – the ‘home’ folder for this experiment.
Within this home-folder, flowdex requires a simple folder structure to properly work. Create that folder structure now within a newly created experiment home-folder called ‘tap_water_home’:

td <- tempdir()
exp_home <- paste0(td, "/tap_water_home") 
dir.create(exp_home)
flowdex::genfs(exp_home) # create the required folder structure in 'tap_water_home'

Continue to data acquisition, or straight to Workflow 2, where you can learn how to extract fluorescence distributions and how to visualize them.