hilbertDisplay         package:HilbertVisGUI         R Documentation

_H_i_l_b_e_r_t _c_u_r_v_e _v_i_s_u_a_l_i_z_a_t_i_o_n

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

     Display one or several long integer vectors in an inetractive
     fashion  by means of the Hilbert curve.

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

     hilbertDisplay( 
           ..., 
           palette      = hilbertDefaultPalette( 
                             1 + min(1000, max(..., na.rm = TRUE))),
           paletteSteps = 1:(ncol(palette)-1),
           naColor      = col2rgb( "gray" ), 
           plotFunc     = simpleLinPlot, 
           names        = NULL,
           sameScale    = FALSE,
           pow2         = FALSE,
           portrait     = TRUE,
           fullLengths  = NULL 
     )

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

     ...: The data vectors to be visualized. This may be integer or
          real vectors.  Care is taken within 'hilbertDisplay' that
          these vectors do not get duplicated,  so that you can pass
          very large vectors. 

 palette: The color palette used to visualize the data. This must be an
          array with 3 row and one column per color, with integers
          ranging from 0 to 255 for the RGB values, i.e. the format
          returned by 'col2rgb'. Use  'col2rgb' to convert if you have
          your palette as character vector. If no  palette is supplied,
          the palette generated by 'hilbertDefaultPalette' is  used,
          scaled to have enough color for the maximum value of all data
          vectors. (At the  moment, this works correctly only for
          integer data.)

paletteSteps: The data value steps for the palette. If the value of a
          bin is below 'paletteSteps[1]', it is deisplayed in the color
          'palette[,1]', if  it is at least 'paletteSteps[1]' but below
          'paletteSteps[2]', color  'palette[2]' is used etc. The
          length of 'paletteSteps' must be one less than the number of
          colors in 'palette'. If no 'colorSteps' argument is supplied,
          the first color is used for bin values below 1, the second
          for values 1 <= v < 2, etc.  

 naColor: The color to be used for bins which contain NAs or correspond
          to data outside the limits of the data vector. Pass a triple
          of RGB values. By  default, "gray" is used.

plotFunc: An R function that is called if you use the "Linear plot"
          function  offer by HilbertCurveDisplay's GUI. If you enable
          this function and then click on a pixel in the display, the
          function supplied as 'plotFunc' is called. If you do not
          supply this parameter, the function 'simpleLinPlot' (part of
          this package) is used. If you supply your own function, it
          must accept two parameters:  'data' and 'info'. 'data' will
          be the currently displayed data vector. Be careful that your
          function does not duplicate it (check with 'tracemem', if in
          doubt) in order to avoid performance problems when dealing
          with large data. The second argument, 'info', is a list,
          supplying the following fields, all of which, except for the
          last one, are single integers: 'info$binLo', 'info$bin', and
          'info$binHi' are the lower, middle, and upper coordinate
          (i.e., vector index) of the bin represented by the pixel onto
           which the user has clicked. 'info$dispLo' and 'info$dispHi'
          are the  lowest and highest index of the part of the vector
          currently displayed. 'info$seqIdx' is the index of the
          currently displayed vector (i.e., its position in the '...'
          argument) and 'ionfo$seqName' is its name. All indices are
          one-based. Your function should plot a region of interest
          around 'data[info$bin]', or do some other useful operation.
          Any return value is ignored. For a very simple example, see
          the body of 'simpleLinPlot'.

   names: The names of the sequences. A character vector. If not
          supplied, the expressions used in the '...' argument, as
          reported by 'substitute' are used.

sameScale: Setting this argument to 'TRUE' pads all but the largest
          vector with 'NA's such that all vectors have the same length.
          (The padding is done "virtually", i.e. no dupliocation in
          memory occurs.) The purpose of this is to make sure that the
          bin size (i.e. the number of values depicted by one pixel)
          stays constant, when using the DisplayHilbertViewer GUI's
          "Prev" and "Next" buttons, which switch the display through
          the supplied data vectors.

    pow2: Setting thsi argument to 'TRUE' pads all vectors virtually
          with 'NA's such that their length becomes a power of 2. The
          purpose of this becomes apparent if you zoom in so much that
          several pixels correspond to the same data vector element.
          Then, without this options, the values take on strange
          fractal forms, while they are square in case of a power-of-2
          length.

portrait: Setting this option to 'FALSE' changes the GUI layout such
          that the controls appear to the right of the curve display
          ("landscape layout") as opposed to the usual case of them
          appearing below ("portrait layout"). This is useful for small
          screens as the GUI window may be two tall to fit on the
          screen in portrait mode.

fullLengths: This option allows you to manually control the padding of
          vectors with 'NA's if you do not like the result of the
          'same.scale' or 'pow2' option. Supply an integer vector with
          as many values as their are vectors in the '...' argument,
          specifying the length including padding for each data vector.
          Passing numbers smaller than the length of the data.vector
          results in only the beginning of the vector being displayed.

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

     Returns an invisible NULL.

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

     Simon Anders, EMBL-EBI, sanders@fs.tum.de

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

     'simpleLinPlot', 'hilbertDefaultPalette'

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

     random <- c( as.integer( runif(100000)*30 ) ) 
     ramp <- c( as.integer( 0:19999/100 ) )
     try( hilbertDisplay( random, ramp ) )

