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): $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) 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`, `subset-methods`, `subset2-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.0.1 Index]