read.FCS {rflowcyt} | R Documentation |
Reading in a raw binary Flow Cytometry Standard (FCS) file
Description
Reads in a Flow Cytometry Standard (FCS) file and outputs an "FCS" R
object.
Usage
read.FCS(fileName, myFCSobj.name="", fcs.type=NULL,
fcs.byte.size =2, fcs.signed=TRUE, fcs.endian="auto",
use.FCS.shortnames = FALSE, no.names = FALSE,
UseS3 = FALSE,
MY.DEBUG = TRUE)
Arguments
fileName |
string of the FCS file location |
myFCSobj.name |
character string of the FCS object name given;
default is "" |
fcs.type |
a list of information (version, byte.size, signed,
endian) about the FCS file; see fcs.type |
fcs.byte.size |
numeric indicating the fcs file byte size,
default is 2 |
fcs.signed |
TRUE if signed binary data, FALSE if unsigned |
fcs.endian |
character string; the endian of the fcs file:
"auto"will automatically determine the endianness
"big"Byte order is 4,3,2,1
"little"Byte order is 1,2,3,4
|
use.FCS.shortnames |
boolean indicating whether or not to use
the short or longnames for the dataframe in the FCS object output,
default is TRUE/to use the short names |
no.names |
boolean indicating whether or not to use the names in
the fcs file for the FCS object output, default is FALSE/to use the
names in the FCS file |
UseS3 |
If true, save in old S3 class structure, else save in new
S4 class strucuture |
MY.DEBUG |
boolean indicating whether or not to print the
debugging statements, default is TRUE/to print |
Details
This function also checks if there are discrepancies between
the data and the metadata in terms of range and size. If there is,
then the data is re-read with different fcs.byte.size (1,2,4,8) and
fcs.signed (TRUE, FALSE) combinations until there is no discrepancy
between the data and the metadata. If there is still a discrepancy,
then the routine is halted. Note: For FCS version 3.0 files, only the
range of the data is checked against what is stated in the metadata
because FCS version 3.0 files have extra elements that are read into
the data.
Value
a "FCS" object |
has the following slots: |
data |
a dataframe of the cells as rows and the variables for
each cell as the columns |
metadata |
a list of the variable names and comments as in the
FCS file which may include the following (for FCS file version 3.2.19):
$PARthe number of columns/parameters
$TOTthe total number of cells/rows
$MODEthe mode of the FCS file
$BEGINANALYSISpart of FCS file heading indicating the
position of the beginning of the analysis portion
$BEGINDATApart of FCS file heading indicating the beginning
of the data portion
$BYTEORDpart of FCS file heading indicating byte order/endian
$BEGINSTEXTpart of FCS file heading indicating beginning of
text
$DATATYPEpart of FCS file heading indicating the type of data
$ENDANALYSISpart of FCS file heading indicating the end of
the analysis portion
$ENDDATApart of FCS file heading indicating the end of the
data portion
$ENDSTEXTpart of FCS file heading indicating the end of the
text portion
$NEXTDATApart of FCS file heading indicating the next data
$PnBNumber of bits reserved for parameter number n
$PnEAmplification type for parameter n
$PnRRange for parameter number n
$ABRTEvents lost due to data acquisition electronic coincidence
$BTIMClock time at beginning of data acquisition
$CELLSDescription of objects measured.
$COMComment
$COMPFluorescence compensation matrix.
$CSMODECell subset mode, number of subsets to which an object may belong
$CSVBITSNumber of bits used to encode a cell subset identifier
$CSVnFLAGThe bit set as a flag for subset n.
$CYTType of flow cytometer
$CYTSNFlow cytometer serial number
$DATEDate of data set acquisition
$ETIMClock time at end of data acquisition
$EXPName of investigator initiating the experiment
$FILName of the data file containing the data set
$GATENumber of gating parameters
$GATINGSpecifies region combinations used for gating
$GnEAmplification type for gating parameter number n
$GnFOptical filter used for gating parameter number n
$GnNName of gating parameter number n
$GnPPercent of emitted light collected by gating parameter n
$GnRRange of gating parameter n
$GnSName used for gating parameter n
$GnTDetector type for gating parameter n
$GnVDetector voltage for gating parameter n
$INSTInstitution at which data acquired
$LOSTNumber of events lost due to computer busy
$OPName of flow cytometry operator
$PknPeak channel number of univariate histogram for parameter n
$PKNnCount in peak channel of univariate histogram for parameter n
$PnFName of optical filter for parameter n
$PnGAmplifier gain used for acquisition of parameter n
$PnLExcitation wavelength for parameter n
$PnNShort name for parameter n
$PnOExcitation power for parameter n
$PnPPercent of emitted light collected by parameter n
$PnSLong name/Name used for parameter n in the dataset
$PnTDetector type for parameter n
$PnVDetector voltage for parameter n
$PROJName of the experiment project
$RnIGating region for parameter number n
$RnWWindow settings for gating region n
$SMNOSpecimen (tube or well) label
$SRCSource of the specimen (patient name,cell types)
$SYSType of computer and its operating system
$TIMESTEPTime step for time parameter
$TRTrigger parameter and its threshold
$UNICODEUNICODE code page for string type keyword values
RFACSadd$>>$...metadata information added using rflowcyt
package via addParameter ,
extractGatedData
|
WARNING
The following scenerios may happen in which read.FCS
has failed:
Problem 1A number of names assigned to the columns of the data is
different from the number of columns.
Possible SolutionUse
read.FCS again and choose a different fcs.byte.size value
(such as 1, 2, 4, 8, 12, 16, etc.)
Problem 2The file has been read properly by read.FCS, but the
range of the resulting FCS R-object is wrong (ie, there are negative
values when all values should be positive).
Possible SolutionsUse
read.FCS again, and choose a different fcs.signed value
(either TRUE or FALSE) and/or choose a different fcs.endian value
(either "big", or "little" or "auto").
Note
Thanks to Peter Rabinovitch for informaton and Julie McElrath lab
for the example data.
Author(s)
A.J. Rossini and J.Y. Wan
See Also
summary
, print
,
extractGatedData
, addParameter
,
"[-methods"
, "[[-methods"
,
fcs.type
Examples
if (require(rfcdmin)) {
## obtaining the location of the fcs files in the data
FACSCAN256<- paste(system.file("fcs", package="rfcdmin"),
"facscan256.fcs",
sep="/")
## reading in the FCS files
FCSobj1<-read.FCS(FACSCAN256)
## If a known type, then:
## read.FCS(fileName, fcs.type=foo)
## currently, the type doesn't have to be an argument
## the read.FCS function will check against different
## fcs.byte.size and fcs.signed options
## if the data is not the correct size or
## range as in the metadata
## NOTE: for FCS version 3.0 only
## the ranges NOT the sizes are checked
}
[Package
rflowcyt version 1.4.0
Index]