flowdexit: Read in FCS Files and Extract Data
In bpollner/flowdex: Extract Fluorescence Distribution Data from FCS Files and Recalculate to Events per Volume
View source: R/gen-functions.R
flowdexit R Documentation
Read in FCS Files and Extract Data
Description
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.
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.
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.
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/.
See Also
flowdex, makefdmat
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()
fdmat2 <- flowdexit(patt = "T5", gateStrat = "gateStrat_2")
fdmat_small <- flowdexit(patt = "T4", expo = FALSE, stf = FALSE)
#
fdmat_small
fdmat_small[[1]]
#
setwd(old_wd)
bpollner/flowdex documentation built on March 31, 2022, 3:21 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/gen-functions.R
| flowdexit | R Documentation |
Read in FCS Files and Extract Data
Description
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 |
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
|
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: |
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. |
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.
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.
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/.
See Also
flowdex, makefdmat
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()
fdmat2 <- flowdexit(patt = "T5", gateStrat = "gateStrat_2")
fdmat_small <- flowdexit(patt = "T4", expo = FALSE, stf = FALSE)
#
fdmat_small
fdmat_small[[1]]
#
setwd(old_wd)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.