\name{readPlateList}
\alias{readPlateList}
\title{Read a collection of plate reader data files}
\description{
  Reads a collection of plate reader data files into a \code{cellHTS} object.
  The names of the files, plus additional information
  (plate number, repeat number, assay/treatment/condition)
  is expected in a tab-delimited table specified
  by the argument \code{filename}.  
}
\usage{
readPlateList(filename, path=dirname(filename), name, importFun, verbose=interactive())
}
\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{path}{a character of length 1 indicating the path in
    which to find the plate reader files.}
  \item{name}{a character of length 1 with the experiment name.}
  \item{importFun}{a function to read the data files.
    The default function works for a certain file format,
    such as that of the example files provided with this package.
    If your plate reader software produces files with a different
    format, the import function needs to be adapted. See details.}
  \item{verbose}{a logical value, if TRUE, the function reports
    some of its intermediate progress.}
}

\details{The file table is expected to be a tab-delimited file with at
  least three columns named \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, and can be used to denote, for example, different variants of the
  assay, treatments, incubation times, conditions, etc.

  \code{importFun} can be used to define a custom function to import
  data files. The \code{importFun} function should accept as its first argument
  names from the \code{Filename} column of the file table (which in
  principle do not need to be individual files, they could also be handles for
  database entries or pointers into relevants parts of a file). It
  should return a list with two components:
  \itemize{
    \item The first component should be a \code{data.frame} with the following columns
    \itemize{
     \item \code{well}, a character vector with the well identifier in the plate.
     \item \code{val}, the intensity values measured in that well.
   }
   and with as many rows as there are wells in the plate.
   \item The second component 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[cellHTS2: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[cellHTS2]{getEnVisionRawData}}.
}

\value{
  An object of class \code{\linkS4class{cellHTS}}, which extends the
  class 
  \code{\link[Biobase:class.NChannelSet]{NChannelSet}}. 
  After calling this function, the content of the following slots is as follows:
  \item{assayData}{an object of class \code{\link[Biobase]{AssayData}}
    containing the imported measurement data. Each matrix represents a
    single channel, and each run corresponds to a
    column. Thus, the total number of rows in each matrix corresponds to
    the product between the number of wells per plate and the number of
    assay plates.}
  \item{phenoData}{information about the runs, infered from the
    \code{plateList} file: which replicate, which variant of the
    assay, treatment, incubation times etc.}
  \item{featureData}{the information about the plate and well
    identifiers for each plate measurement are stored in columns
    \code{plate} 
    and \code{well} of this slot.}
  \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}.}
}

\seealso{
To read input files obtained in a HTanalyser plate reader see \code{\link{readHTAnalystData}}.
}

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

\references{
Boutros, M., Bras, L.P. and Huber, W. (2006) Analysis of cell-based RNAi screens, \emph{Genome Biology} \bold{7}, R66.
}


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


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

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

}
\keyword{manip}