\name{readIllumina}
\alias{readIllumina}
\title{Read bead-level Illumina data}
\description{
  Reads bead-level ouput by Illumina's BeadScan software. 
}
\usage{
  readIllumina(dir = ".", useImages = FALSE, illuminaAnnotation = NULL, sectionNames = NULL, metricsFile = "Metrics.txt", forceIScan = FALSE, ...)
}

\arguments{
  \item{dir}{Directory from which to read the data, the default being the current working directory. }
  \item{useImages}{Boolean value specifying if bead intensities should be read directly from the source text files or calculated using the bead centre coordinates and image files.}
  \item{illuminaAnnotation}{Character string specifiying the Illumina platform on which the data were generated. This is optional and will help to automate some analyses on expression data. Currently the choices for this argument are Humanv4, Humanv3, Humanv2, Humanv1, Mousev2, Mousev1, Mousev1p1, Ratv1.}
  \item{sectionNames}{Optional vector of character strings corresponding to section names to be read in. Typically these are the 10 digit numeric ID of Illumina chip followed by an underscore and capital letter 
}
  \item{metricsFile}{optional name of a metrics file to be read in from the directory. Defaults to Metrics.txt}
  \item{forceIScan}{Only necessary for data from iScan machines.  When TRUE, this argument forces beadarray to read data from files withe the "perBeadFile.txt" extension, rather than seeking a file per swath.  Use this if you are receiving the error "iScan data detected. This must first be processed with the function processSwathData()", but don't have access to .locs and .tif files for the array.}
  \item{\dots}{
other arguments to pass when reading bead-level text files
}
}

\details{The bead-level data can be generated by any Illumina assay (expression, genotyping, methylation) and via BeadChips or Sentrix Array Matrix. However, some operations within the package are optimised for expression data. For optimal performance, BeadScan needs to be modified to output coordinates for each bead and to include outliers. See http://www.compbio.group.cam.ac.uk/Resources/illumina/index.html for details.

If present, the function will automatically read the following files from the directory

.txt Text file that lists the ID, coordinates and intensity for every decoded bead on an array section. The intensities have been subjected to a local background correction. If \code{useImages = FALSE} these intensities will be used as a starting point for analysis

.sdf Illumina\'s Sample Description File for the entire chip or SAM. This is used within beadarray to determine the physical properties of a section.

.locs Locations of all beads on the array (i.e. including all those that could not be decoded)

Metrics.txt Illumina\'s metrics that are produced at the time of scanning.

Separate functionality exists to read and manipulate TIFF images that may be found in the same directory. See \code{\link{readTIFF}}.

}

\value{
Returns an object of class \code{\link{beadLevelData-class}}
}

\author{Mike Smith, Mark Dunning, Andy Lynch}

\keyword{IO}