readCelUnits           package:affxparser           R Documentation

_R_e_a_d_s _p_r_o_b_e-_l_e_v_e_l _d_a_t_a _o_r_d_e_r_e_d _a_s _u_n_i_t_s (_p_r_o_b_e_s_e_t_s) _f_r_o_m _o_n_e _o_r _s_e_v_e_r_a_l _A_f_f_y_m_e_t_r_i_x _C_E_L _f_i_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Reads probe-level data ordered as units (probesets) from one or
     several Affymetrix CEL files by using the unit and group
     definitions in the corresponding Affymetrix CDF file.

_U_s_a_g_e:

     readCelUnits(filenames, units=NULL, stratifyBy=c("nothing", "pmmm", "pm", "mm"), cdf=NULL, ..., addDimnames=FALSE, dropArrayDim=TRUE, transforms=NULL, reorder=TRUE, readMap=NULL, verbose=FALSE)

_A_r_g_u_m_e_n_t_s:

filenames: The filenames of the CEL files.

   units: An 'integer' 'vector' of unit indices specifying which units
          to be read.  If 'NULL', all units are read.

stratifyBy: Argument passed to low-level method 'readCdfUnits'.

     cdf: A 'character' filename of a CDF file, or a CDF 'list'
          structure.  If 'NULL', the CDF file is searched for by
          'findCdf'() first starting from the current directory and
          then from the directory where the first CEL file is.

     ...: Arguments passed to low-level method 'readCel', e.g. 'readXY'
          and 'readStdvs'.

addDimnames: If 'TRUE', dimension names are added to arrays, otherwise
          not.  The size of the returned CEL structure in bytes
          increases by 30-40% with dimension names.

dropArrayDim: If 'TRUE' and only one array is read, the elements of the
          group field do _not_ have an array dimension.

transforms: A 'list' of exactly 'length(filenames)' 'function's.  If
          'NULL', no transformation is performed. Intensities read are
          passed through the corresponding transform function before
          being returned.

 reorder: If 'TRUE', cell indices are read in order to speed up the
          reading.  If 'FALSE', cells are read in the order as given. 
          For more details, see help on the same argument in
          'readCel'().

 readMap: A 'vector' remapping cell indices to file indices. If 'NULL',
          no mapping is used.

 verbose: Either a 'logical', a 'numeric', or a 'Verbose' object
          specifying how much verbose/debug information is written to
          standard output. If a Verbose object, how detailed the
          information is is specified by the threshold level of the
          object. If a numeric, the value is used to set the threshold
          of a new Verbose object. If 'TRUE', the threshold is set to
          -1 (minimal). If 'FALSE', no output is written (and neither
          is the 'R.utils' package required). 

_V_a_l_u_e:

     A named 'list' with one element for each unit read.  The names
     corresponds to the names of the units read. Each unit element is
     in turn a 'list' structure with groups (aka blocks). Each group
     contains requested fields, e.g. 'intensities', 'stdvs', and
     'pixels'. If more than one CEL file is read, an extra dimension is
     added to each of the fields corresponding, which can be used to
     subset by CEL file.

     Note that neither CEL headers nor information about outliers and
     masked cells are returned.  To access these, use 'readCelHeader'()
     and 'readCel'().

_A_u_t_h_o_r(_s):

     Henrik Bengtsson (<URL: http://www.braju.com/R/>)

_R_e_f_e_r_e_n_c_e_s:

     [1] Affymetrix Inc, Affymetrix GCOS 1.x compatible file formats,
     June 14, 2005. <URL: http://www.affymetrix.com/support/developer/>

_S_e_e _A_l_s_o:

     Internally, 'readCelHeader'(), 'readCdfUnits'() and 'readCel'()
     are used.

_E_x_a_m_p_l_e_s:

     for (zzz in 0) {

     # Scan current directory for CEL files
     files <- list.files(pattern="[.](c|C)(e|E)(l|L)$")
     files <- files[!file.info(files)$isdir]
     if (length(files) == 0)
       break

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Benchmarking reading cells in order or not.
     #
     # The difference will be large the more files that are read.
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     units <- 56:256
     nunits <- length(units);

     # Make sure enough files are read to measure the speed up
     files <- rep(files, length.out=5)
     nfiles <- length(files);

     t1 <- system.time({
       cel <- readCelUnits(files, units=units, reorder=TRUE)
     })[3]
     cat(sprintf("Time   [ordered]: %6.2fs = %.2fms/(unit & array) [1.00x]\n",
                                               t1, 1000*t1/nunits/nfiles))
     rm(cel); gc()

     t2 <- system.time({
       cel <- readCelUnits(files, units=units, reorder=FALSE)
     })[3]
     cat(sprintf("Time [unordered]: %6.2fs = %.2fms/(unit & array) [%.2fx]\n",
                                        t2, 1000*t2/nunits/nfiles, t2/t1))
     rm(cel); gc()

     # Clean up
     rm(files, t1, t2)

     } # for (zzz in 0)

