\name{readPlateData}
\alias{readPlateData}
\title{Read a collection of plate reader data files}
\description{
  Reads a collection of plate reader data files into a data.frame.
  The names of the files, plus additional information
  (plate number, repeat number) is expected in a tab-delimited table specified
  by the argument \code{x}.  
}
\usage{
readPlateData(filename, path=dirname(filename), name, importFun, verbose=TRUE, plateType)
}
\arguments{
  \item{filename}{the name of the file table (see details).
    This argument is just passed on to the \code{\link{read.table}}
    function, so any of the valid argument
    types for \code{\link{read.table}} are valid here, too.}
  \item{name}{a character of length 1 with the experiment name.}
  \item{path}{a character of length 1 indicating the path in
    which to find the plate reader files. By default, 
    it can extract the path from \code{filename}.}
   \item{importFun}{a function that should be used to read each plate result file. The default function works for plate reader data files. See details.}
   \item{verbose}{a logical value, if TRUE, the function reports some of its intermediate progress.}
   \item{plateType}{(deprecated argument) a character of length 1 giving the format of the plate: "96" for  96-well plate format, or "384" for a 384-well plate format.}
}

\details{The file table is expected to be a tab-delimited file with at
  least three columns, and column names \code{Filename}, \code{Plate},
  and \code{Replicate}. The contents of the columns \code{Plate} and
  \code{Replicate} are expected to be integers. Further columns are
  allowed.

  We distinguish between \emph{plates} and \emph{plate result file}.
  A plate result file contains the measurements results for all
  replicates and all channels of a plate, which is the physical carrier
  of the reagents. 

\code{importFun} can be used to define other functions to import other data files, such as flow cytometry data files, etc. The \code{importFun} function should receive as an input the name of a result plate file to read, and return a list with two components:
\itemize{
 \item The first component should be a 'data.frame' with the following slots:
   \itemize{
     \item \code{well}, a character vector with the well identifier in the plate.
     \item \code{val}, the intensity values measured at each well.
  }
 \item The second component of this list should be a character vector containing a copy of the imported input data file (such as the output of \code{\link[base:readLines]{readLines}}). It should be suitable to be used as input for \code{\link[base:writeLines]{writeLines}}, since it will be used to reproduce the intensity files that are linked in the HTML quality reports generated by \code{\link[cellHTS:writeReport]{writeReport}}.
 }
For example, to import plate data files from EnVision plate reader, set \code{importFun=getEnVisionRawData} or \code{importFun=getEnvisionCrosstalkCorrectedData}. See function \code{\link[cellHTS:getEnVisionRawData]{getEnVisionRawData}}.

}

\value{
  An object of class \code{"cellHTS"}, which is currently implemented as
  a list with elements
  \item{name}{copy of the input argument \code{name}}
  \item{xraw}{an array of dimension plateSize x number of plates x
    number of replicates x number of channels, containing the imported
    measurement data.}
  \item{pdim}{a numeric vector of length 2 containing the number of rows
    and columns in a plate. The product of these two numbers is the
    first dimension of \code{xraw}. This corresponds to the plate    	
format used in the screen, and it is automatically determined from the plate result files. The allowed formats are 96-well  or 384-well plates.
}
  \item{batch}{an integer vector with the batch number (1, 2, ...)
    for each plate. Its length corresponds to the second dimension of 
    of \code{xraw}.}
  \item{plateList}{a data.frame containing what was read from input file
    \code{x}, plus a column \code{status} of type character: it contains
    the string "OK" if the data import
    appeared to have gone well, and the respective error or warning
    message otherwise.}
  \item{intensityFiles}{a list, where each component contains a
    copy of the imported input data files. Its length corresponds to the
    number of rows of \code{plateList}.}
  \item{state}{a logical vector representing the processing status of
    the object.}
}

\author{W. Huber \email{huber@ebi.ac.uk}, Ligia Braz \email{ligia@ebi.ac.uk}}

\seealso{
\code{\link[cellHTS:getEnVisionRawData]{getEnVisionRawData}}
}




\examples{
    datadir <- system.file("KcViabSmall", package = "cellHTS")
    x <- readPlateData("Platelist.txt", "KcViabSmall", path=datadir)

    ## To read data files obtained from an EnVision plate reader:
    datadir <- system.file("EnVisionExample", package = "cellHTS")
    x <- readPlateData("platelist.txt", "EnVisionEx",
          importFun=getEnVisionRawData, path=datadir)

       ## to get the cross talk corrected data:
       y <- readPlateData("platelist.txt", "EnVisionEx", 
           importFun=getEnVisionCrosstalkCorrectedData, path=datadir)

}
\keyword{manip}