In bpollner/flowdex: Extract Fluorescence Distribution Data from FCS Files and Recalculate to Events per Volume

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
#
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")
#
exp_home <- paste0(td, "/tap_water_home") 
dir.create(exp_home)
# setwd(exp_home)
flowdex::genfs(exp_home) # create the required folder structure in 'tap_water_home'
# knitr::opts_knit$set(root.dir = paste0(tempdir(), "/tap_water_home"))

After running the setup as described in Get Started, it is time for data acquisition -- go and measure your samples, then come back and put your fcs files into the folder 'fcsFiles'.

Simulate Data Acquisition

Simulate data acquisition now by copying the files from 'flowdexTutorial/fcsFiles' to 'tap_water_home/fcsFiles':

td <- tempdir()
from <- list.files(paste0(td, "/flowdex_tutorial/fcsFiles"), full.names = TRUE)
to <- paste0(td, "/tap_water_home/fcsFiles")
cs <- file.copy(from, to)
all(cs)

Using Structured ID String and Dictionary {#using-structured-id-string-and-dictionary}

If so desired, it is possible to generate class- and numerical variables further describing each sample resp. the dataset by providing a structured character string to the Sample-ID field of each sample in the GUI of the FCM-machine at the time of data acquisition.

This character string will then later be expanded using a dictionary (located in 'tap_water_home/dictionary') to expand the abbreviations to its long names.

Using the Structured ID String

As the assigning of the structured character string to each sample has to be done at the time of data acquisition in the GUI of the FCM-machine, we´d like to explain the process by showing and describing what was used in the case of our tutorial data.

Lets consider for example the sample named 'N_na_GPos_T4_th1_b3.fcs'.:\ This is a sample of the experiment-group ('GPos'), from day 4 ('T4'), first third of beakers ('th1'), and from that the beaker number 3 ('b3').\ The structured character string now contains elements and groups, each separated by a dedicated single character. The default value for separating groups is ; and that for separating elements is :.

There can be as many groups as desired. A single group consists of exactly two elements: the key and the value, separated per default by : . For the sample above, the input in the sample-ID field in the GUI of the FCM-machine at the time of data acquisition now would be:

tr: GPos; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b3 

Here, we have 7 groups: tr, Td, wt, ap, th, ha and bk, all separated by a ;. 'tr' e.g. will be expanded to 'C_treatment' as defined in the dictionary. 'GPos' is the value in the first group, meaning that this sample belongs to the experiment group (denoted as 'GPos'). The next group 'Td: 4' means that the treatment time for this sample was 4 days, and so on.

• The first part of an element is always the short name, the abbreviation that gets expanded to its long name using the dictionary. The second part of the element is its actual value. The first part can be thought of as the column name in a spreadsheet, while the second part is the actual value within that column.
• The order of the groups is not relevant, they can be in different order for different samples (but as this could be confusing during data acquisition, this is not recommended). If an erroneous sample ID is provided, it can be repaired later using the function repairSID().
• The data, i.e. the class- and numerical variables assigned to each sample can later be accessed via the slot cyTags in the object created by e.g. function flowdexit(), and they will also be exported to file (if exporting to xlsx). These data can be very helpful and convenient when further analyzing the fluorescence distributions.

Using the Dictionary

Considering the sample-IDs present in our tutorial fcs files, we require a dictionary translating the present abbreviations to their long names. For that, copy the dictionary from flowdex_tutorial/dictionary/dictionary.xlsx to tap_water_home/dictionary:

from <- list.files(paste0(td, "/flowdex_tutorial/dictionary"), full.names = TRUE)
to <- paste0(td, "/tap_water_home/dictionary")
file.copy(from, to)

Open the copied xlsx file, look at the column named 'Abbreviation': For each element name (the first part of an element) in the sample ID there is an entry in the dictionary, along with its long name (the final 'column name' when thinking in a spreadsheet).

Defining Class- and Numerical Variables

• By prepending the long names in the dictionary with dedicated strings it is possible to define each group as being either a class-variable or a numerical variable.

• The default string for class variables is C_ , and that for numerical variables is Y_ .

• Prepending the long names in the dictionary with either class-variable or numerical variable prefix is mandatory.

By now we should have 108 fcs files in 'tap_water_home/fcsFiles' and one file 'dictionary.xlsx' in the folder 'tap_water_home/dictionary'.

Continue to Workflow 1.

bpollner/flowdex documentation built on March 31, 2022, 3:21 a.m.