\HeaderA{read.FCS}{Reading in a raw binary Flow Cytometry Standard (FCS) file}{read.FCS}
\keyword{classes}{read.FCS}
\keyword{character}{read.FCS}
\begin{Description}\relax
Reads in a Flow Cytometry Standard (FCS) file and outputs an "FCS" R
object.
\end{Description}
\begin{Usage}
\begin{verbatim}
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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{fileName}] string of the FCS file location 
\item[\code{myFCSobj.name}] character string of the FCS object name given;
default is ""
\item[\code{fcs.type}] a list of information (version, byte.size, signed,
endian) about the FCS file; see \code{\LinkA{fcs.type}{fcs.type}}
\item[\code{fcs.byte.size}] numeric indicating the fcs file byte size,
default is 2 
\item[\code{fcs.signed}] TRUE if signed binary data, FALSE if unsigned
\item[\code{fcs.endian}] character string; the endian of the fcs file:
\item["auto"] will automatically determine the endianness
\item["big"] Byte order is 4,3,2,1
\item["little"] Byte order is 1,2,3,4

\item[\code{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 
\item[\code{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
\item[\code{UseS3}] If true, save in old S3 class structure, else save in new
S4 class strucuture
\item[\code{MY.DEBUG}] boolean indicating whether or not to print the
debugging statements, default is TRUE/to print
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{a "FCS" object}] has the following slots:
\item[\code{data}] a dataframe of the cells as rows and the variables for
each cell as the columns
\item[\code{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):
\item[\$PAR] the number of columns/parameters
\item[\$TOT] the total number of cells/rows
\item[\$MODE] the mode of the FCS file
\item[\$BEGINANALYSIS] part of FCS file heading indicating the
position of the beginning of the analysis portion
\item[\$BEGINDATA] part of FCS file heading indicating the beginning
of the data portion
\item[\$BYTEORD] part of FCS file heading indicating byte order/endian
\item[\$BEGINSTEXT] part of FCS file heading indicating beginning of
text
\item[\$DATATYPE] part of FCS file heading indicating the type of data
\item[\$ENDANALYSIS] part of FCS file heading indicating the end of
the analysis portion
\item[\$ENDDATA] part of FCS file heading indicating the end of the
data portion
\item[\$ENDSTEXT] part of FCS file heading indicating the end of the
text portion
\item[\$NEXTDATA] part of FCS file heading indicating the next data
\item[\$PnB] Number of bits reserved for parameter number n
\item[\$PnE] Amplification type for parameter n
\item[\$PnR] Range for parameter number n
\item[\$ABRT] Events lost due to data acquisition electronic coincidence
\item[\$BTIM] Clock time at beginning of data acquisition
\item[\$CELLS] Description of objects measured.
\item[\$COM] Comment
\item[\$COMP] Fluorescence compensation matrix.
\item[\$CSMODE] Cell subset mode, number of subsets to which an object may belong
\item[\$CSVBITS] Number of bits used to encode a cell subset identifier
\item[\$CSVnFLAG] The bit set as a flag for subset n.
\item[\$CYT] Type of flow cytometer
\item[\$CYTSN] Flow cytometer serial number
\item[\$DATE] Date of data set acquisition
\item[\$ETIM] Clock time at end of data acquisition
\item[\$EXP] Name of investigator initiating the experiment
\item[\$FIL] Name of the data file containing the data set
\item[\$GATE] Number of gating parameters
\item[\$GATING] Specifies region combinations used for gating
\item[\$GnE] Amplification type for gating parameter number n
\item[\$GnF] Optical filter used for gating parameter number n
\item[\$GnN] Name of gating parameter number n
\item[\$GnP] Percent of emitted light collected by gating parameter n
\item[\$GnR] Range of gating parameter n
\item[\$GnS] Name used for gating parameter n
\item[\$GnT] Detector type for gating parameter n
\item[\$GnV] Detector voltage for gating parameter n
\item[\$INST] Institution at which data acquired
\item[\$LOST] Number of events lost due to computer busy
\item[\$OP] Name of flow cytometry operator
\item[\$Pkn] Peak channel number of univariate histogram for parameter n
\item[\$PKNn] Count in peak channel of univariate histogram for parameter n
\item[\$PnF] Name of optical filter for parameter n
\item[\$PnG] Amplifier gain used for acquisition of parameter n
\item[\$PnL] Excitation wavelength for parameter n
\item[\$PnN] Short name for parameter n
\item[\$PnO] Excitation power for parameter n
\item[\$PnP] Percent of emitted light collected by parameter n
\item[\$PnS] Long name/Name used for parameter n in the dataset
\item[\$PnT] Detector type for parameter n
\item[\$PnV] Detector voltage for parameter n
\item[\$PROJ] Name of the experiment project
\item[\$RnI] Gating region for parameter number n
\item[\$RnW] Window settings for gating region n
\item[\$SMNO] Specimen (tube or well) label
\item[\$SRC] Source of the specimen (patient name,cell types)
\item[\$SYS] Type of computer and its operating system
\item[\$TIMESTEP] Time step for time parameter
\item[\$TR] Trigger parameter and its threshold
\item[\$UNICODE] UNICODE code page for string type keyword values
\item[RFACSadd$>>$...] metadata information added using rflowcyt
package via \code{addParameter},
\code{extractGatedData}


\end{ldescription}
\end{Value}
\begin{Section}{WARNING}
The following scenerios may happen in which read.FCS
has failed:

\item[Problem 1] A number of names assigned to the columns of the data is
different from the number of columns.

\item[Possible Solution] Use
read.FCS again and choose a different fcs.byte.size value
(such as 1, 2, 4, 8, 12, 16, etc.)


\item[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).

\item[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").
\end{Section}
\begin{Note}\relax
Thanks to Peter Rabinovitch for informaton and Julie McElrath lab
for the example data.
\end{Note}
\begin{Author}\relax
A.J. Rossini and J.Y. Wan
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{summary}{summary}}, \code{\LinkA{print}{print}},
\code{\LinkA{extractGatedData}{extractGatedData}}, \code{\LinkA{addParameter}{addParameter}},
\code{\LinkA{"[-methods"}{"[.Rdash.methods"}}, \code{\LinkA{"[[-methods"}{"[[.Rdash.methods"}},
\code{fcs.type}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

  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
  }

\end{ExampleCode}
\end{Examples}

