readIllumina {beadarray} | R Documentation

## Read bead-level data into R

### Description

Uses .csv or .txt and TIFFs (where available) to load information about each bead on each array in a BeadChip or SAM experiment.

### Usage

    readIllumina(arrayNames=NULL, path=".", textType=".txt",
            annoPkg=NULL, useImages=TRUE,
            singleChannel=TRUE, targets=NULL,
            imageManipulation="sharpen", backgroundSize=17,
            storeXY=TRUE, sepchar="_", dec=".", metrics=FALSE,
            metricsFile="Metrics.txt", backgroundMethod="subtract",
            offset=0, normalizeMethod="none",
            tiffExtGrn="_Grn.tif", tiffExtRed="_Red.tif", ...)

### Arguments

`arrayNames` | character vector containing names of arrays to be read in. If `NULL`, all arrays that can be found in the current working directory will be read in.
`path` | character string specifying the location of files to be read by the function
`textType` | character string specifiying the extension of the files which store the bead-level information. Typically `".txt"`, `".csv"` or `"_perBeadFile.txt"`.
`annoPkg` | character string specifying the annotation package for the arrays being read in (only available for certain expression arrays at present). Default value is `"illuminaProbeIDs"` which is not an annotation package, and indicates that Illumina bead IDs have been used to identify each bead.
`useImages` | logical. If TRUE, the foregound and background values are retrieved from the TIFFs. When FALSE, the intensity values in the text files are used. Note that background values will not be available (set to 0) when FALSE, as the current option in BeadScan is to store background corrected intensities.
`singleChannel` | logical. Set to TRUE if the data is single channel (Green images only) or FALSE for two-colour (both Green and Red data available).
`targets` | `data.frame` containing sample information
`imageManipulation` | character string specifying which image analysis method to use. The current options are `"none"` (no image manipulation or `"sharpen"` (the Illumina sharpening mask will be used prior to the foreground averages being calculated).
`backgroundSize` | integer value which defines the size of the n x n region (in pixels) used to calculate local background values. Default value is 17
`storeXY` | logical scalar, indicating whether the xy coordinates should be stored
`sepchar` | character string which separates the row and column positions in the file names (default value is `"_"`)
`dec` | character used in the files for decimal points. The default value is `"."`
`metrics` | logical scalar, indicating whether the scanner metrics file `metricsFile` is to be read in
`metricsFile` | name of the scanner metrics file (`"Metrics.txt"` by default)
`backgroundMethod` | method to use for background correcting the data. Options are `"none"`, `"subtract"`, `"half"`, `"minimum"`, `"edwards"`, `"normexp"` or `"rma"`
`offset` | numeric value to add to intensities
`normalizeMethod` | method to use to normalize the background corrected bead-level data. Options are `"none"`, `"quantile"` and `"vsn"`. Note that the normalization occurs at the bead-level and is only available for two-colour data at this stage
`tiffExtGrn` | character string specifying the file extension of the Cy3 (Green) images. Default is `"_Grn.tif"`
`tiffExtRed` | character string specifying the file extension of the Cy5 (Red) images (where present). Default is `"_Red.tif"`
`...` | other arguments

### Details

This function can be used to read in bead-level information from the raw .tif and .csv or .txt files output by BeadScan.

Note that the .txt or .csv files must contain the raw data for each bead on each array/strip, not the summarised data. The .csv or .txt files specify the location and identity of each bead on the array and must contain columns for the $x$ and $y$ position of each bead as well as a ProbeID. For two-colour arrays, this information is required for each channel.

The foreground and background intensities of each bead are calculated from the images when `useImages=TRUE`. For the foreground calculations the sharpening mask used by Illumina is applied prior to averaging over the 9 pixels in a 3 x 3 square closest to the bead centre by default (`imageManipulation="sharpen"`). If `imageManipulation="none"`, no sharpening is performed. The local background estimate for each bead is calculated by averaging the 5 minimum pixels in a 17 x 17 square around each bead centre from the unsharpened image. The size of this window is controlled by the `backgroundSize` argument. If a bead is too close to the edge of the image, it is ignored.

When `useImages=FALSE`, the intensities from the .txt or .csv files are stored as the foreground values for each bead. Note that the values stored in these files have already undergone a local background adjustment, so the background values are set to 0.

To keep track of the samples hybridised to each array, we recommend using a `targets` `data.frame`, which lists each strip/array in the rows, and experimental information about each strip/array in the columns (sample, array name, etc.) Targets information can easily be created and saved in tab delimited text format, read in using `read.table` and passed to `readIllumina` using the `targets` argument.

The pairs of strips from a BeadChip can be combined when the data is summarised with `createBeadSummaryData`.

The function creates a `BeadLevelList` containing foreground and background intensities for each bead on each array.

NOTE: Reading in bead-level data, particularly with the TIFFs is memory intensive. For example, reading in text and image data from a Human-6 BeadChip requires several Gigabytes of RAM. If you have limited memory, it is recommnded that you read in the data using the `useImages=FALSE` option.

### Value

BeadLevelList object

### Author(s)

Mark Dunning, Mike Smith

### Examples

    #BLData = readIllumina()

    #targets = read.table("targets.txt", header=T)

    #targets
    #May take a while to run
    #BLData.s = readIllumina(arrayNames=target$Institute.Sample.Label, targets=targets, imageManipulation="none")

    #Create foreground intensities without using sharpening. Should take less time
    #BLData.ns = readIllumina(arrayNames=targets$Institute.Sample.Label, targets=targets, imageManipulation="sharpen")

[Package beadarray version 1.12.1 Index]