\name{read.FCS}
\alias{read.FCS}
\title{ 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{
  \item{fileName}{ string of the FCS file location }
  \item{FCSobj.name}{character string of the FCS object name given;
    default is ""}
  \item{fcs.type}{a list of information (version, byte.size, signed,
    endian) about the FCS file; see \code{\link{fcs.type}}}
  \item{fcs.byte.size}{ numeric indicating the fcs file byte size,
    default is 2 }
  \item{fcs.signed}{TRUE if signed binary data, FALSE if unsigned}
  \item{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{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{UseS3}{If true, save in old S3 class structure, else save in new
    S4 class strucuture}
  \item{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{
  \item{a "FCS" object}{has the following slots:}
  \item{data}{a dataframe of the cells as rows and the variables for
    each cell as the columns}
  \item{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}}
 
  }
}
\author{A.J. Rossini, J.Y. Wan and N. Le Meur}
\note{
  Thanks to Peter Rabinovitch for informaton and Julie McElrath lab
  for the example data.
}
\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).
    }
}
\seealso{ \code{\link{summary}}, \code{\link{print}},
  \code{\link{extractGatedData}}, \code{\link{addParameter}},
  \code{\link{"[-methods"}}, \code{\link{"[[-methods"}},
  \code{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)

    
  }

}
\keyword{classes}
\keyword{character}