readIllumina            package:beadarray            R Documentation

_R_e_a_d _b_e_a_d-_l_e_v_e_l _d_a_t_a _i_n_t_o _R

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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", ...)

_A_r_g_u_m_e_n_t_s:

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

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     BeadLevelList object

_A_u_t_h_o_r(_s):

     Mark Dunning, Mike Smith

_E_x_a_m_p_l_e_s:

     #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")

