writeReport             package:cellHTS2             R Documentation

_C_r_e_a_t_e _a _d_i_r_e_c_t_o_r_y _w_i_t_h _H_T_M_L _p_a_g_e_s _o_f _l_i_n_k_e_d _t_a_b_l_e_s _a_n_d _p_l_o_t_s
_d_o_c_u_m_e_n_t_i_n_g _t_h_e _c_o_n_t_e_n_t_s _o_f _a _c_e_l_l_H_T_S _e_x_p_e_r_i_m_e_n_t

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

     Creates a directory with HTML pages of linked tables and plots
     documenting the contents of the preprocessing of a 'cellHTS'
     object.

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

     writeReport(
       raw,
       normalized=NULL,
       scored=NULL,
       cellHTSlist=NULL,
       outdir,
       force=FALSE,
       map=FALSE,
       plotPlateArgs=FALSE,
       imageScreenArgs=NULL,
       posControls,
       negControls,
       mainScriptFile=NA)

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

     raw: the intitial raw 'cellHTS' object. See details.

normalized: a normalized 'cellHTS' object. See details.

  scored: a scored 'cellHTS' object. See details.

cellHTSlist: a list of 'cellHTS' objects. See details. Note: this
          argument is deprecated. Please use the separate arguments
          'raw', 'normalized' and 'scored' instead. 

  outdir: a character of length 1 with the name of a directory where to
          write the report HTML file and images. If the directory does
          not exist, it is created. If it exists and is not empty, then
          the behaviour depends on the value of 'force'.  If 'outdir'
          is missing, it is set to 'file.path(getwd(),
          name(cellHTSlist[['xraw']]))', i.e. a directory with the name
          of the cellHTS object(s) in the current working path.

   force: a logical value, determines the behaviour of the function if
          'outdir' exists and is not empty.  If 'force' is 'TRUE', the
          function overwrites (removes and recreates) 'outdir',
          otherwise it casts an error.

     map: a logical value indicating whether tooltips with the
          annotation should be added to the plate plots and image
          screen. Default value is FALSE.

plotPlateArgs: either a list with parameters for the plate plots of the
          per plate quality report pages, or a logical scalar with
          values 'FALSE' or 'TRUE'.  If 'FALSE', the plate plots are
          omitted, this option is here because the production of the
          plate plots takes a long time.  See details.

imageScreenArgs: a list with parameters for the function 'imageScreen'.
          See details.

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

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

mainScriptFile: The path to the R script generating the current report.
          We strongly advice to store this script in the compendium for
          future reference. 

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

     The function has to be called with the mandatory rgument 'raw'
     corresponding to an unnormalized 'cellHTS' object (i.e.
     'state(cellHTSlist[["raw"]])["normalized"]=FALSE'). Additional
     optional arguments are:



        *  '"normalized"': a 'cellHTS' object containing normalized
           data (i.e.
           'state(cellHTSlist[["normalized"]])["normalized"]=TRUE' and
           'state(cellHTSlist[["normalized"]])["scored"]=FALSE').

        *  '"scored"': a 'cellHTS' object containing data scored data
           (i.e. 'state(cellHTSlist[["scored"]])["scored"]=TRUE'). If
           this component is available, then
           'cellHTSlist[["normalized"]]' should also be given.


     All of the above arguments have to be 'cellHTS' objects containing
     data from the same experiment, but in different preprocessing
     stages.

     The 'cellHTS' argument is deprecated and should no be used
     anymore.

     The following elements are recognized for 'plotPlateArgs' and
     passed on to 'plotPlate': 'sdcol', the color scheme for the
     standard deviation plate plot, 'sdrange', the sd range to which
     the colors are mapped, 'xcol', the color scheme for the intensity
     plate plot, 'xrange', the intensity range to which the colors are
     mapped.  If an element is not specified, default values are used.

     The following elements are recognized for 'imageScreenArgs' and
     passed on to 'imageScreen': 'ar', aspect ratio, 'zrange', range,
     'anno', gene annotation for the image map (if 'map=TRUE').

     '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 acccessed via 'wellAnno(objects)').

     If the 'cellHTS' object containing normalized data was provided in
     'cellHTSlist', the length of 'posControls' and 'negControls'
     should be equal to the number of channels in this 'cellHTS' object
     ('dim(Data(cellHTSlist[["normalized"]]))[3]'). Otherwise, the
     length of these vectors should be equal to the number of channels
     in the unpreprocessed 'cellHTS' object (i.e.,
     'dim(Data(cellHTSlist[["raw"]]))[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 annotate the negative controls.  The content of
     'posControls' and 'negControls' will be passed to 'regexpr' for
     pattern matching within the well annotation given in column
     'controlStatus' of the 'featureData' slot of the 'cellHTS' object.
     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.

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

     By default, tooltips doing the mapping between the probe
     annotation and the plate wells are not added to the plate plots
     and to the overall screen plot. If any of the 'cellHTS' objects in
     'cellHTSlist' is annotated, the probe annotation uses the
     information contained whether in column 'GeneSymbol' or column
     'GeneID' (if the former is missing) of the 'featureData' slot of
     the annotated 'cellHTS' object. Otherwise, the mapping simply uses
     the well identifiers.

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

     The function is called for its side-effect. It returns a character
     with the full path and name of the report index file, this is an
     HTML file which can be read by a web browser.

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

     Florian Hahne fhahne@fhcrc.org, Ligia P. Bras ligia@ebi.ac.uk,
     Wolfgang Huber huber@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:

     'plotPlate', 'imageScreen'

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

         data(KcViabSmall)
         pCtrls <- c("pos") 
         nCtrls <- c("neg") 
     ## Not run: 
         ## or for safety reasons (not a problem for the current well annotation, however) 
          pCtrls <- c("^pos$") 
          nCtrls <- c("^neg$")
         writeReport(raw=KcViabSmall, posControls=pCtrls, negControls=nCtrls)
         ## same as 
         ## writeReport(raw=KcViabSmall)
         xn <- normalizePlates(KcViabSmall, scale="multiplicative", log=FALSE, method="median")
         xsc <- scoreReplicates(xn, sign="-", method="zscore")
         xsc <- summarizeReplicates(xsc, summary="min")
         ## to turn on the tooltips in the plate plots and in the image screen plot:
         writeReport(raw=KcViabSmall, normalized=xn, scored=xsc, force=TRUE, map=TRUE, plotPlateArgs = TRUE, imageScreenArgs=list(zrange=c(-4,4)))
         
     ## End(Not run)

