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
fnto 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.patternofread.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 functioncheckRepairFcsFileswhich 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.
Link
Please refer also to https://bpollner.github.io/flowdex/.
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)