Skip to contents

Read in fcs files from a specified folder, produce a gating set, add gates as defined in the gating strategy file, extract fluorescence distribution data from each gate, possibly re-calculate the fluorescence distribution to events per volume unit, export all data to file and save the R-object holding all the data to file as well.

Usage

flowdexit(
  fn = ".",
  patt = NULL,
  gateStrat = ".",
  foN.gateStrat = ".",
  type.gateStrat = ".",
  comp = ".",
  tx = ".",
  channel = ".",
  name.dict = ".",
  foN.dict = ".",
  type.dict = ".",
  expo = TRUE,
  expo.gate = ".",
  expo.name = ".",
  expo.type = ".",
  expo.folder = ".",
  fcsRepair = FALSE,
  stf = TRUE,
  rcv = ".",
  verbose = "."
)

Arguments

fn

Character length one. The name of the folder where FCS files should be read from. If left at the default '.', the folder name as defined in the settings file (key: 'foN_fcsFiles') will be used.

patt

A regular expression defining a possible subset of FCS files residing in the directory specified by fn to read in. Only matching patterns will be included.

gateStrat

Character length one. The name of the file defining the gating strategy. If left at the default '.', the name as defined in the settings file (key: 'fiN_gateStrat') will be used.

foN.gateStrat

Character length one. The name of the folder where the file defining the gating strategy and the gate definitions reside. If left at the default '.', the name as defined in the settings file (key: 'foN_gating') will be used.

type.gateStrat

Character length one, can be either 'csv' or 'xlsx'. The type of file defining the gating strategy. Currently, csv and xlsx files are supported. If left at the default '.', the filetype as defined in the settings (key: 'dV_gateStratInputType') file will be used.

comp

Logical. If compensation should be applied or not. If left at the default '.', the value as defined in the settings file (key 'dV_comp') will be used.

tx

Character length one. The transformation applied to *all* channels within the individual flow sets. If left at the default '.', the value as defined in the settings file (key 'dV_tx') will be used. (Currently only 'fjbiex' is implemented.)

channel

A regular expression indicating which channels, i.e. which columns to keep from the original flowFrames; is passed down to argument column.pattern of read.flowSet. Set to NULL to read data from all channels. If left at the default '.', the value as defined in the settings file (key 'dV_channel') will be used.

name.dict

Character length one. The name of the dictionary. If left at the default '.', the value as defined in the settings file (key 'dD_dict_name') will be used.

foN.dict

Character length one. The name of the folder where the dictionary resides. If left at the default '.', the value as defined in the settings file (key 'foN_dictionary') will be used.

type.dict

Character length one. The filetype of the dictionary. Can be one of 'csv' or 'xlsx'. If left at the default '.', the value as defined in the settings file (key 'dD_dict_type') will be used.

expo

Logical, if extracted data should exported at all.

expo.gate

Which gate to export. NULL or numeric or character length one. Set to NULL to export data from all those gates defined in the gating strategy where 'keepData' is set to TRUE. Provide a character length one with a gate name or the number of that gate as defined in the gating strategy to export data from this gate only. If left at the default '.', the value as defined in the settings file (key 'dE_exportGate') will be used.

expo.name

Character length one. The name of the file holding the exported fluorescence distribution(s). If left at the default '.', the value as defined in the settings file (key 'fiN_dataExport') will be used.

expo.type

Character length one. The filetype of the data export. Possible values are 'csv' and 'xlsx'. If left at the default '.', the value as defined in the settings file (key 'dE_exportType') will be used.

expo.folder

Character length one. The name of the folder where exported data should reside. If left at the default '.', the value as defined in the settings file (key 'foN_rawData') will be used.

fcsRepair

Logical. If set to TRUE, fcs-files in the folder specified at argument 'fn' will be checked for multiplied entries in the keywords, as after some testing the author came to the humble conclusion that these multiplied keywords can be the reason for the error message:
"The HEADER and the TEXT segment define different starting point ... to read the data".
If 'fcsRepair' is set to TRUE, all except the last of each multiplied keyword will be removed and the fcs file will be saved to disc, overwriting the original fcs file without further warning.
Use the function checkRepairFcsFiles which does offer more options to manually check and repair afflicted fcs files. There, it is possible to display multiplied keywords and to select which one to keep.

stf

Logical. If the resulting object of class 'fdmat' should be saved to file in the data export folder. Defaults to TRUE. If saved, the name of the gating strategy used to generate the data will be appended to the filename.

rcv

Logical. If the fluorescence distributions should be re-calculated to events per volume unit. If left at the default '.', the value as defined in the settings file (key 'dV_doRecalcToVolume') will be used.

verbose

Logical. If status messages should be displayed. If left at the default '.', the value as defined in the settings file (key 'dV_verbose') will be used.

Value

An (invisible) object of class-fdmat containing a list holding an object of class-fdmat_single in each list element, which in turn contains a matrix holding the fluorescence distribution of a single gate, and the overall data for events per volume unit in the slot eventsPerVol.

Details

While function 'flowdexit' returns fluorescence distributions re-calculated to events per volume unit, the gating set that was produced in the way of obtaining the fluorescence distribution data gets assigned to the environment 'gsenv' under the name 'gatingSet'. Hence, it can be accessed via gsenv$gatingSet.

It is paramount to obtain the correct volume factor from the help / the manual of the FCM-machine that did produce the fcs files. Please see section 'Calculating Events per Volume Unit' for more details.

Calculating Events per Volume Unit

The calculation of events per volume unit is performed via the following code: round((nrEvRaw / vols) * volFac , 0), with nrEvRaw being the number of (raw) events in a specific channel as saved in the fcs file, vols being the acquired volume of a sample, and volFac being a factor obtained from the manual of the FCM-machine. The 'volFac' is a number provided by the manufacturer of the FCM-machine / of the volumetric measurement module. It is the number required to convert raw events back to events per volume. It must be obtained from the manual of the FCM-machine resp. the volumetric measurement module. The volFac is stored in the flowdex_settings.R file (key: 'dV_volumeFactor').

Regarding Compensation

Due to the circumstances when developing this code, it was never required to apply any kind of compensation. The functionality to apply compensation was therefore never tested or verified. It is strongly advised to use caution when applying compensation. It might well be necessary to modify the source code (https://github.com/bpollner/flowdex) of this package in order to achieve correct compensation results (compensation is applied in the function makeGatingSet).

Exporting Data

If data are exported to xlsx, additional data like the metadata describing the parameters that lead to the calculation of the fluorescence distribution, the cyTags and the gating strategy are saved in an extra sheet as well. If exporting to csv, only the fluorescence data are exported.

Please refer also to https://bpollner.github.io/flowdex/.

See also

Examples

td <- tempdir()
data_source <- "https://github.com/bpollner/data/raw/main/flowdex_examples/flowdex_examples.zip"
check_download_data(td, data_source)
exp_home <- paste0(td, "/flowdex_examples")
old_wd <- getwd()
setwd(exp_home)
#
assign("get_settings_from_flowdex_package_root", TRUE, pos=.GlobalEnv)
# only required to make the examples run automatically
# you should not call 'assign' if you run the examples manually
# the effect of setting 'get_settings_from_flowdex_package_root' to TRUE
# is that the file 'flowdex_settings.R' in 'root' of the installed package
# 'flowdex' will be sourced instead of the one in the user-defined location.
#
fdmat <- flowdexit()
#> 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.
fdmat2 <- flowdexit(patt = "T5", gateStrat = "gateStrat_2")
#> Reading in fcs files... ok. 
#> Producing gating set... Applying fjbiexp transformation... ok. 
#> Gating: (6 gates)
#> done!
#> DNA+: Extracting binned data on FITC.A (res=220) and recalc. to volume... ok. 
#> HighSSC_ffif: Extracting binned data on FSC.A (res=220) and recalc. to volume... ok. 
#> Exporting data (2 gates) to xlsx...ok. 
#> fdmat-object saved.
fdmat_small <- flowdexit(patt = "T4", expo = FALSE, stf = FALSE)
#> 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. 
#
fdmat_small
#> An object of class 'fdmat' [package 'flowdex'] with 6 slots
#> containing data from 6 samples in 1 gate.
#> Fluorescence distribution has been re-calculated to events per ml.
#> (use 'object[[1]]' to inspect the first list element containing the first fluorescence distribution)
#> 
#> 
#> Slot 'metadata':
#>                     gateName     gateDef extractOn res   flRange  apc coR coV
#> dV_doRecalcToVolume     DNA+ BactStainV1    FITC.A 220 1250,4000 TRUE  10 125
#>                      rcv   igp  smo smN smP ncpwl
#> dV_doRecalcToVolume TRUE FALSE TRUE  11   5     4
#> 
#> 
#> Slot 'cyTags':
#>                         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_GPos_T4_th1_b1.fcs        GPos        4       nativ        no     th1
#> N_na_GPos_T4_th1_b2.fcs        GPos        4       nativ        no     th1
#> N_na_GPos_T4_th1_b3.fcs        GPos        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_GPos_T4_th1_b1.fcs    ha1       b1
#> N_na_GPos_T4_th1_b2.fcs    ha1       b2
#> N_na_GPos_T4_th1_b3.fcs    ha1       b3
#> 
#> 
#> Slot 'gateStrat':
#>   GateName Parent GateOnX GateOnY GateDefinition extractOn minRange maxRange
#> 1     DNA+   root  FITC.A PerCP.A    BactStainV1    FITC.A     1250     4000
#>   keepData
#> 1     TRUE
#> 
#> 
#> Slot 'pData':
#>                                                                             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_GPos_T4_th1_b1.fcs tr: GPos; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b1
#> N_na_GPos_T4_th1_b2.fcs tr: GPos; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b2
#> N_na_GPos_T4_th1_b3.fcs tr: GPos; Td: 4; wt: nativ; ap: no; th: th1; ha: ha1; bk: b3
#>                                            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_GPos_T4_th1_b1.fcs N_na_GPos_T4_th1_b1.fcs 15:01:20  70000
#> N_na_GPos_T4_th1_b2.fcs N_na_GPos_T4_th1_b2.fcs 15:03:47  45000
#> N_na_GPos_T4_th1_b3.fcs N_na_GPos_T4_th1_b3.fcs 15:05:36  45000
#> 
#> 
#> Slot 'note':
#> [1] "original"
fdmat_small[[1]]
#> An object of class 'fdmat_single'
#> containing data from 6 samples in 219 fluorescence intensities from flsc1256 to flsc3994
#> derived from gate 'DNA+'.
#> original 
#>                               flsc1256 flsc1269 flsc1281 flsc3969 flsc3981
#> N_na_GNeg_T4_th1_b1.fcs|DNA+ 0.0000000        0 0.000000        0        0
#> N_na_GNeg_T4_th1_b2.fcs|DNA+ 0.0000000        0 0.000000        0        0
#> N_na_GPos_T4_th1_b2.fcs|DNA+ 0.0000000        0 0.000000        0        0
#> N_na_GPos_T4_th1_b3.fcs|DNA+ 0.9324009        0 2.020202        0        0
#>                              flsc3994
#> N_na_GNeg_T4_th1_b1.fcs|DNA+        0
#> N_na_GNeg_T4_th1_b2.fcs|DNA+        0
#> N_na_GPos_T4_th1_b2.fcs|DNA+        0
#> N_na_GPos_T4_th1_b3.fcs|DNA+        0
#> (showing only the first and last columns and rows)
#> 
#> Overall data for events per volume unit:
#>                         events_ml mean is_filtered events_ml_orig
#> N_na_GNeg_T4_th1_b1.fcs    297516 1985       FALSE         297516
#> N_na_GNeg_T4_th1_b2.fcs    379780 1913       FALSE         379780
#> N_na_GNeg_T4_th1_b3.fcs    276220 1913       FALSE         276220
#> N_na_GPos_T4_th1_b1.fcs    278657 1893       FALSE         278657
#> N_na_GPos_T4_th1_b2.fcs    373333 1923       FALSE         373333
#> N_na_GPos_T4_th1_b3.fcs    148022 1954       FALSE         148022
#
setwd(old_wd)