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, FCSobj.name="", fcs.type=NULL, 
         fcs.byte.size =2, fcs.signed=TRUE, 
         use.FCS.shortnames = FALSE, no.names = FALSE,
         UseS3 = FALSE,
         MY.DEBUG = TRUE)

Arguments

fileName string of the FCS file location
FCSobj.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
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):
$PAR
the number of columns/parameters
$TOT
the total number of cells/rows
$MODE
the mode of the FCS file
$BEGINANALYSIS
part of FCS file heading indicating the position of the beginning of the analysis portion
$BEGINDATA
part of FCS file heading indicating the beginning of the data portion
$BYTEORD
part of FCS file heading indicating byte order/endian
$BEGINSTEXT
part of FCS file heading indicating beginning of text
$DATATYPE
part of FCS file heading indicating the type of data
$ENDANALYSIS
part of FCS file heading indicating the end of the analysis portion
$ENDDATA
part of FCS file heading indicating the end of the data portion
$ENDSTEXT
part of FCS file heading indicating the end of the text portion
$NEXTDATA
part of FCS file heading indicating the next data
$PnB
Number of bits reserved for parameter number n
$PnE
Amplification type for parameter n
$PnR
Range for parameter number n
$ABRT
Events lost due to data acquisition electronic coincidence
$BTIM
Clock time at beginning of data acquisition
$CELLS
Description of objects measured.
$COM
Comment
$COMP
Fluorescence compensation matrix.
$CSMODE
Cell subset mode, number of subsets to which an object may belong
$CSVBITS
Number of bits used to encode a cell subset identifier
$CSVnFLAG
The bit set as a flag for subset n.
$CYT
Type of flow cytometer
$CYTSN
Flow cytometer serial number
$DATE
Date of data set acquisition
$ETIM
Clock time at end of data acquisition
$EXP
Name of investigator initiating the experiment
$FIL
Name of the data file containing the data set
$GATE
Number of gating parameters
$GATING
Specifies region combinations used for gating
$GnE
Amplification type for gating parameter number n
$GnF
Optical filter used for gating parameter number n
$GnN
Name of gating parameter number n
$GnP
Percent of emitted light collected by gating parameter n
$GnR
Range of gating parameter n
$GnS
Name used for gating parameter n
$GnT
Detector type for gating parameter n
$GnV
Detector voltage for gating parameter n
$INST
Institution at which data acquired
$LOST
Number of events lost due to computer busy
$OP
Name of flow cytometry operator
$Pkn
Peak channel number of univariate histogram for parameter n
$PKNn
Count in peak channel of univariate histogram for parameter n
$PnF
Name of optical filter for parameter n
$PnG
Amplifier gain used for acquisition of parameter n
$PnL
Excitation wavelength for parameter n
$PnN
Short name for parameter n
$PnO
Excitation power for parameter n
$PnP
Percent of emitted light collected by parameter n
$PnS
Long name/Name used for parameter n in the dataset
$PnT
Detector type for parameter n
$PnV
Detector voltage for parameter n
$PROJ
Name of the experiment project
$RnI
Gating region for parameter number n
$RnW
Window settings for gating region n
$SMNO
Specimen (tube or well) label
$SRC
Source of the specimen (patient name,cell types)
$SYS
Type of computer and its operating system
$TIMESTEP
Time step for time parameter
$TR
Trigger parameter and its threshold
$UNICODE
UNICODE 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 1
A number of names assigned to the columns of the data is different from the number of columns.
Possible Solution
Use read.FCS again and choose a different fcs.byte.size value (such as 1, 2, 4, 8, 12, 16, etc.)
Problem 2
The 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 Solutions
Use read.FCS again, and choose a different fcs.signed value (either TRUE or FALSE).

Note

Thanks to Peter Rabinovitch for informaton and Julie McElrath lab for the example data.

Author(s)

A.J. Rossini, J.Y. Wan and N. Le Meur

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)

    
  }


[Package rflowcyt version 1.14.0 Index]