plotAlongChrom          package:tilingArray          R Documentation

_P_l_o_t _s_i_g_n_a_l_s _a_n_d _s_e_g_m_e_n_t_a_t_i_o_n _f_o_r _a _r_e_g_i_o_n _o_f _a _c_h_r_o_m_o_s_o_m_e

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

     Plot signals and segmentation for a region of a chromosome

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

     plotAlongChrom(segObj, y, probeAnno, gff,
         isDirectHybe=FALSE, 
         what = c("dots"), ## "heatmap"
         chr, coord, highlight,
         colors, doLegend=FALSE,
         featureExclude=c("chromosome", "nucleotide_match", "insertion"),
         featureColorScheme=1, extras, 
         rowNamesHeatmap, rowNamesExtras, ylab, ylabExtras, main, 
         colHeatmap=colorRamp(brewer.pal(9, "YlGnBu")), 
         colExtras=colorRamp(brewer.pal(9, "Reds")), 
         sepPlots=FALSE, reOrder=TRUE, ...)

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

  segObj: Either an environment or an object of S4 class
          'segmentation'. See _Details_.

       y: a numeric vector or matrix containing the signal to be
          plotted. See _Details_.

probeAnno: environment with probe annotations. See _Details_, and
          package 'davidTiling' for an example.

     gff: data frame with genome annotation from the GFF file.

isDirectHybe: logical scalar: if TRUE, the mapping of probes to genomic
           strands is reversed with respect to the default. This is
          appropriate for data  from a direct RNA hybridization that
          used no reverse transcription.

    what: character scalar indicating which signal visualization to
          plot.  Can be either 'dots' to plot each probe intensity with
          a point, or 'heatmap' to produce a colorscale representation
          of the intesities.

     chr: integer of length 1 indicating the chromosome number to plot.

   coord: integer vector of length 2 containing the start and end
          coordinates (in bases) for the plot.

highlight: (optional) list with two elements: a single numeric value
          'coord' and a character 'strand'. If present, this position
          is marked by a vertical red bar on the coordinate axis.  The
          color can be changed using the 'colors' argument below.

  colors: (optional) named character vector. If missing,  a default
          color scheme is used: 'c("+"="#00441b", "-"="#081d58",
          "duplicated"="grey", "cp"="#101010",  "highlight"="red",
          "threshold"="grey")',  where the first three elements refer
          to the colors of data points and the  last three to the
          colors of lines in the plot.

doLegend: logical: should the plot contain a legend?

featureExclude: character vector of names of feature types (in 'gff')
          that should not be plotted. Default is '"chromosome"', 
          '"nucleotide_match"' and '"insertion"'.  Additional
          possibilities  include: '"ARS"', '"repeat_region"', 
          '"repeat_family"' and '"nc_primary_transcript"'.

featureColorScheme: numeric scalar, used to select a color scheme for
          the  boxes representing genomic features such as coding
          sequences, ncRNAs etc.  Currently the only value supported is
          1 (see 'plotAlongChromLegend' or 'plotFeatures' for further
          information).

  extras: a matrix containing additional values to be plotted along the
           chromosome in a separate panel (such as p-values).  This
          option is only  available when 'y' is specified.  These
          values should be on the scale [0,1].

rowNamesHeatmap: character vector of row names for the main heatmap.

rowNamesExtras: character vector of row names for the extra heatmap.

    ylab: character label for y-axis of main plot.

ylabExtras: character label for y-axis on 'extras' panel (if
          specified).

    main: character: plot title.

colHeatmap: function describing color scheme for the main heatmap plot
          (defaults to 'YlGnBu' from RColorBrewer package).

colExtras: function describing color scheme for the extra heatmap plot
          (if specified)    (defaults to 'Reds' from RColorBrewer
          package).

sepPlots: logical scalar.  If TRUE, each column of intensities in
          'segObj' or  'y' is plotted separately (maximum of 3) in the
          same figure. When FALSE, the average  is plotted.  This
          argument is only used when 'what' is set to 'dots'.

 reOrder: logical scalar (only used when sepPlots is TRUE). If TRUE,
          the first  column of intensities is printed at the bottom of
          each plot, and the subsequent columns  are plotted above.  If
          FALSE, the first appears at the top, and the subsequent
          columns  are plotted below.

     ...: further arguments that can be passed to the functions that
          implement the 'what' option above (see 'plotSegmentationDots'
          and  'plotSegmentationHeatmap') or 'gff' plotting (see
          'plotFeatures' and 'plotAlongChromLegend').

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

     _Intensities_: There are two alternative, mutually exclusive ways
     of providing the intensities that are to be plotted to this
     function.

        1.  Via the parameters 'y' and 'probeAnno'. In this case, 'y'
           is a matrix of intensities, whose rows correspond to probes
           on the array, and its columns to different conditions, time
           points, etc. It is also acceptable that 'y' is provided as a
           vector, in which case it is converted to an 'nrow(y) x 1'
           matrix. 'probeAnno' is an environment whose elements
           correspond to target sequences (e.g. chromosome strands) and
           that contain integer vectors of length 'nrow(y)' with
           information about the probes: start and end positions of
           their alignment to the target sequence, their row indices in
           'y', the type of alignment (is it perfect? is is unique?).
           For example, the start positions and indices of probes for
           the + strand of chromosome 1 would be described by
           environment elements '"1.+.start"' and '"1.+.index"'.

        2.  Via the parameter 'segObj'.

     _segObj_: This can be either an object of S4 class 'segmentation'
     or an environment that by convention contains a certain set of
     objects. Future work on this package will focus on the S4 class
     'segmentation'. The 'environment' option is provided for backward
     compatibility.

     _Explanation of the environment_: the intended workflow is as
     follows: Use the script 'segment.R' (in the 'inst/scripts'
     directory of this package) to generate segmentations. This can be
     run in parallel on several processors, separately for each
     chromosome and strand. The results of this are stored in files of
     the name '1.+.rda', '1.-.rda', '2.+.rda', and so forth, typically
     within a dedicated directory. Then use the script 'readSegments.R'
     to collect the 'R' objects in these '.rda' files into the
     environment. It contains three types of data:

        *  microarray intensities in along-chromosome order.

        *  the segmentation objects (output of findSegments).

        *  a dataframe named 'segScore' with segment scores; it can be
           missing iff 'nrBasesPerSeg' is present,

        *  a numeric scalar names 'theThreshold', which is used to 
           draw a horizontal "threshold" line in the plot.

     _... and the different signal visualization methods ('what'
     option)_: If 'what=="dots"', the argument
     'showConfidenceIntervals' can  be a logical scalar to choose
     whether vertical dashed lines are drawn for the confidence
     interval. In any case, these are only drawn if they are present in
     the 'segmentation' object in 'segObj'.

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

     Wolfgang Huber <huber@ebi.ac.uk>

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

       ## 1. see viewSegmentation.R script in the inst/scripts directory
       ## 2. (newer): segmentation.Rnw
      

