summarizeChannels          package:cellHTS          R Documentation

_N_o_r_m_a_l_i_z_a_t_i_o_n _a_n_d _t_r_a_n_s_f_o_r_m_a_t_i_o_n _o_f _d_u_a_l-_c_h_a_n_n_e_l _d_a_t_a

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

     Normalizes and/or transforms dual-channel data 'xraw' of a
     'cellHTS' object by applying the function defined in 'fun'.

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

     summarizeChannels(x,
         fun = function(r1, r2, thresh) ifelse(r1>thresh, log2(r2/r1), as.numeric(NA)),
         adjustPlates, zscore, ...)

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

       x: a 'cellHTS' object that has been configured.

     fun: a user-defined function for the two channel summarization.
          'fun' takes two numeric vectors and returns a numeric vector
          of the same length. The default is to take the log2-ratio
          between the second and first channels, with a threshold on
          'r1' shown above in the _Usage_ section that should be set by
          the user.

adjustPlates: scalar character string indicating the normalization
          method to apply to adjust for plate-to-plate variations (and
          possibly well-to-well variations). This is done _before_
          applying 'fun'. Allowed values are '"median"', '"mean"',
          '"shorth"', '"POC"', '"NPI"', '"negatives"' and 'Bscore'.  If
          'adjustPlates' is missing (the default), no plate-wise
          correction will be performed. 

  zscore: indicates if the _z_-scores should be determined after
          normalization and transformation. If missing (default), the
          data will not be scored. Otherwise, it should be a character
          string, either "+" or "-", specifying the sign to use for the
          _z_-scores.

     ...: Further arguments that get passed on to the function
          implementing the normalization method chosen by
          'adjustPlates'.  See the _Details_ section and the
          'normalizePlates' function.

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

     For each plate and replicate of a two-color experiment, the
     function defined in 'fun' is applied to relate the intensity
     values in the two channels of the 'cellHTS' object. The default is
     to  take the log2-ratio between the second and first channels,
     with a threshold on  'r1' (see the _Usage_ section). This
     threshold should be ajusted by the  user according to the data.
     For an example, see the _Examples_ section.

     If 'adjustPlates' is not missing, the values for each channel will
     be corrected for plate effects _before_ applying 'fun', by
     considering the chosen normalization method. The available options
     are  'adjustPlates="median"' (median scaling),
     'adjustPlates="mean"' (mean scaling),  'adjustPlates="shorth"'
     (scaling by the midpoint of the shorth),  'adjustPlates="POC"'
     (percent of control),  'adjustPlates="negatives"' (scaling by the
     average on the negative controls), 'adjustPlates="NPI"'
     (normalized percent inhibition) and  'adjustPlates="Bscore"' (B
     score method).  For more details about these normalization
     options, please refer to 'normalizePlates'. By default,
     'adjustPlates' is missing.

     If 'zscore' is not missing, a robust _z_-score is calculated based
     on the channel-summarized measurements. The _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'.  The allowed values for 'zscore' ("+" or "-") are
     used to set the sign of  the calculated _z_-scores. See
     'summarizeReplicates' for more details.

_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', except in the
     dimension corresponding to the number of channels, since the
     two-channel intensities have been combined into one intensity
     value.

     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:

     'normalizePlates', 'Bscore', 'summarizeReplicates'

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

      ## Not run: 
         datadir <- system.file("DualChannelScreen", package = "cellHTS")
         x <- readPlateData("Platelist.txt", "TwoColorData", path=datadir)
         x <- configure(x, "Plateconf.txt", "Screenlog.txt", "Description.txt", path=datadir)
         table(x$wellAnno)

         ## Define the controls for the different channels:
         negControls=vector("character", length=dim(x$xraw)[4])

         ## channel 1 - gene A
         ## case-insensitive and match the empty string at the beginning and end of a line (to distinguish between "geneA" and "geneAB", for example, although this is not a problem for the well annotation in this example)

         negControls[1]= "(?i)^geneA$"  
         ## channel 2 - gene A and geneB
         negControls[2]= "(?i)^geneA$|^geneB$" 
         posControls = vector("character", length=dim(x$xraw)[4])
         ## channel 1 - no controls
         ## channel 2 - geneC and geneD
         posControls[2]="(?i)^geneC$|^geneD$"

         writeReport(x, posControls=posControls, negControls=negControls)
         ## In this example, we first normalize each channel separately by plate median scaling. 
         ## Then, we define a low intensity threshold for the measurements in the constitutive channel R1, 
         ## which will be set to the 5
         x = summarizeChannels(x, fun = function(r1, r2, 
                  thresh=quantile(r1, probs=0.05, na.rm=TRUE)) ifelse(r1>thresh, log2(r2/r1), as.numeric(NA)),
           adjustPlates="median") 
         ## Note that the plate median scaling is applied to each channel, prior to channel summarization.
         ## Define the controls for the normalized intensities (only one channel):
         negControls = vector("character", length=dim(x$xnorm)[4])
         ## For the single channel, the negative controls are geneA and geneB 
         negControls[1]= "(?i)^geneA$|^geneB$" 
         posControls = vector("character", length=dim(x$xnorm)[4])
         ## For the single channel, the negative controls are geneC and geneD 
         posControls[1]="(?i)^geneC$|^geneD$"
         writeReport(x, force=TRUE, plotPlateArgs=list(xrange=c(-3,3)), 
              posControls=posControls, negControls=negControls)
      ## End(Not run)

