getDynamicRange           package:cellHTS2           R Documentation

_P_e_r-_p_l_a_t_e _d_y_n_a_m_i_c _r_a_n_g_e _o_f _a _c_e_l_l_H_T_S _o_b_j_e_c_t

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

     Calculates per-plate dynamic range of data stored in a 'cellHTS'
     object.

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

     getDynamicRange(x, 
     verbose=interactive(), 
     definition, 
     posControls, 
     negControls)

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

       x: a configured 'cellHTS' object. See details.

 verbose: a logical, if 'TRUE' the function reports some of its
          intermediate progress. The default is the state of
          'interactive()'.

definition: a character string with possible values "ratio" or
          "difference". See details.

posControls: (optional) a list or vector of regular expressions
          specifying the name of the positive controls. See details.

negControls: (optional) a vector of regular expressions specifying the
          name of the negative controls. See details.

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

     'x' should be an already configured 'cellHTS' object
     ('state(x)["configured"]=TRUE'), so that the information about the
     well annotation of the plates is available.

     The per-plate dynamic ranges are calculated for the data stored in
     slot 'assayData' of 'x'. This can be raw data, normalized data or
     scored data.

     If 'definition="difference"', the dynamic range is calculated as
     the absolute difference between the arithmetic average on positive
     and negative controls.

     If 'definition="ratio"', the dynamic range is calculated as the
     ratio between the geometric mean on positive and negative
     controls.

     _NOTE:_ the argument 'definition' should only be set to '"ratio"'
     if data are in positive scale!

     If 'definition' is missing it is determined based on the scale of
     the data. By default, if data are in positive scale, definition is
     set to '"ratio"', otherwise, it is set to '"difference'.

     'posControls' and 'negControls' should be given as a vector of
     regular expression patterns specifying the name of the positive(s)
     and negative(s) controls, respectivey, as provided in the plate
     configuration file  (and accessed via 'wellAnno(x)'). The length
     of these vectors should be equal to the current number of channels
     in  'x' ('dim(Data(x))[3]'). By default, if 'posControls' is not
     given, 'pos' will be taken as the name for the wells containing
     positive controls. Similarly, if 'negControls' is missing, by
     default 'neg' will be considered as the name used to annotated the
     negative controls.  The content of 'posControls' and 'negControls'
     will be passed to 'regexpr' for pattern matching within the well
     annotation given in 'wellAnno(x)' (see examples). If no controls
     are available for a given channel, use '""' or 'NA' for that
     channel. For example, 'posControls = c("", "(?i)^diap$")' means
     that channel 1 has no positive controls, while 'diap' is the
     positive control for channel 2.

     The arguments 'posControls' and 'negControls' are particularly
     useful in multi-channel data since the controls might be
     reporter-specific, or after normalizing multi-channel data.

     If there are different positive controls, the dynamic range is
     calculated between each of the positive controls and the negative
     controls.

     In the case of a two-way assay, where two types of "positive"
     controls are used in the screen ("activators" and "inhibitors"),
     'posControls' should be defined as a list with two components
     (called 'act' and 'inh'), each of which should be vectors of
     regular expressions of the same length as the current number of
     reporters (as explained above). The dynamic range is calculated
     between each type of positive control ('activators' or
     'inhibitors') and the negative controls.

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

     The function generates a list with the per-plate dynamic ranges in
     each channel and each replicate. The average dynamic range between
     replicates is also given. Each element of this list is an array of
     dimensions 'nrPlates x (nrReplicates + 1) x nrChannels', and is
     named by the positive controls. In the case of a two-way assay,
     these elements are called 'activators' and 'inhibitors', while for
     a one-way assay, the elements have the same name of the positive
     controls. See Examples section.

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

     Ligia P. Bras ligia@ebi.ac.uk

_R_e_f_e_r_e_n_c_e_s:

     Boutros, M., Bras, L.P. and Huber, W. (2006) Analysis of
     cell-based RNAi screens, _Genome Biology_ *7*, R66.

_S_e_e _A_l_s_o:

     'configure', 'writeReport'

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

         data(KcViabSmall)
         ## pCtrls <- c("pos") 
         ## nCtrls <- c("neg") 
         ## or for safety reasons (not a problem for the current well annotation, however) 
         pCtrls <- c("^pos$") 
         nCtrls <- c("^neg$")
         dr <- getDynamicRange(KcViabSmall, definition="ratio", posControls=pCtrls, negControls=nCtrls)
         ## same as: 
         ## getDynamicRange(KcViabSmall)
         
         x <- normalizePlates(KcViabSmall, scale="multiplicative", log=TRUE, method="median", varianceAdjust="none")
         try(drn <- getDynamicRange(x, definition="ratio"))
         drn <- getDynamicRange(x, definition="difference")

