normalizePlates           package:cellHTS           R Documentation

_P_l_a_t_e-_w_i_s_e _d_a_t_a _n_o_r_m_a_l_i_z_a_t_i_o_n, _a_n_d _d_a_t_a _t_r_a_n_s_f_o_r_m_a_t_i_o_n

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

     Normalization of the data 'xraw' in a cellHTS object. This is done
     separately for each plate, replicate and channel. Optionally, a
     data transformation such as 'log', and a transformation to
     _z_-scores can be performed.

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

     normalizePlates(x, normalizationMethod="median", transform, zscore, posControls, negControls, ...)

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

       x: a 'cellHTS' object that has already been configured. See
          details.

normalizationMethod: a character specifying the normalization method to
          use for performing the per-plate normalization. Allowed
          values are '"median"' (default), '"mean"', '"shorth"',
          '"POC"', '"NPI"', '"negatives"' and 'Bscore'. See details.

transform: a function that takes a numeric vector and returns a numeric
          vector of the same length; for example, the logarithm
          function 'log'.

  zscore: indicates if the data should be centered and scaled after
          normalization and transformation. If missing (default), the
          data will not be centered and scaled. Otherwise, the value of
          this argument should be a character string, either "+" or
          "-", which will be used to set the sign for the calculated
          _z_-scores. See details.

posControls: a vector of regular expressions giving the name of the
          positive control(s). See details.

negControls: a vector of regular expressions giving the name of the
          negative control(s). See details.

     ...: Further arguments that get passed on to the function
          implementing the normalization method chosen by
          'normalizationMethod'. Currently, this is only used for 
          'Bscore'. 

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

     The normalization is performed in a plate-by-plate fashion. 

        *  If 'normalizationMethod="median"' (median scaling), plates
           effects are corrected by dividing each measurement          
           by the median value across wells annotated as 'sample' in
           'x$wellAnno', for each plate and replicate.

        *  If 'normalizationMethod="mean"' (mean scaling), the average
           in the 'sample' wells is consider instead.

        *  If 'normalizationMethod="shorth"' (scaling by the midpoint
           of the shorth), for each plate and replicate, the midpoint
           of the 'shorth' of the distribution of values in the wells
           annotated  as 'sample' is calculated. Then, every
           measurement is divided by this value.

        *  If 'normalizationMethod="POC"' (percent of control), for
           each plate and replicate, each measurement is divided by the
           average of the measurements on the plate positive controls,
           and multiplied by 100.

        *  If 'normalizationMethod="negatives"' (scaling by the
           negative controls), for each plate and replicate, each
           measurement is divided by the median of the measurements on
           the plate negative controls.

        *  If 'normalizationMethod="NPI"' (normalized percent
           inhibition), each measurement is subtracted from the average
           of the intensities on the plate positive controls, and this
           result is divided by the difference between  the means of
           the measurements on the positive and the negative controls.

        *  If 'normalizationMethod="Bscore"' (B score), for each plate
           and replicate, the B score method is applied to remove plate
           effects and row and column biases. NOTE: if the argument
           'transform' is given, the B score method is applied AFTER
           data transformation.

     If 'transform' is not missing, the chosen data transformation is
     applied.  Most commonly, this option can be used to apply a log
     transformation.

     If 'zscore' is not missing, a robust _z_-score for each individual
     measurement will be determined for each plate and each well by
     subtracting the overall 'median' and dividing by the overall
     'mad'. These are taken by considering the distribution of
     intensities (over all plates) in the wells whose content is
     annotated as 'sample'.  The allowed values for 'zscore' ("+" or
     "-") are used to set the sign of the calculated _z_-scores. For
     example, with a 'zscore="-"' a strong decrease in the signal will
     be represented by a positive _z_-score, whereas setting
     'zscore="+"',  such a phenotype will be represented by a negative
     _z_-score.   This option can be set to calculate the results to
     the commonly used convention.

     The arguments 'posControls' and 'negControls' are required for
     applying the normalization methods based on the control
     measurements (that is, when 'normalizationMethod="POC"', or
     'normalizationMethod="NPI"', or
     'normalizationMethod="negatives"').  '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 stored in 'x$wellAnno'). The length of these vectors should
     be equal to the number of reporters used in the screen
     ('dim(x$xraw)[4]') or to 'dim(x$xnorm)[4]', in case 'x' contains
     multi-channel data that have been normalized by combining the
     values from two or more channels. 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
     annotate the negative controls.  The content of 'posControls' and
     'negControls' will be passed to 'regexpr' for pattern matching
     within the well annotation given in 'x$wellAnno' (see examples for
     'summarizeChannels'). 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.

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

     An object of class 'cellHTS', which is a copy of the argument 'x',
     plus an additional slot 'xnorm' containing the normalized data.
     This is an array of the same dimensions as 'xraw'.

     Moreover, the processing status of the 'cellHTS' object is updated
     in the slot 'state' to 'x$state["normalized"]=TRUE'.

     Additional outputs may be given if 'adjustPlates="Bscore"'. Please
     refer to the help page of the 'Bscore' function.

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

     Ligia Braz ligia@ebi.ac.uk, Wolfgang Huber huber@ebi.ac.uk

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

     'Bscore', 'summarizeChannels'

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

         data(KcViabSmall)
         x1 = normalizePlates(KcViabSmall, normalizationMethod="median", zscore="-")
         ## Not run: 
         x2 = normalizePlates(KcViabSmall, normalizationMethod="Bscore", zscore="-")
         
     ## End(Not run)

