hexbinplot              package:hexbin              R Documentation

_T_r_e_l_l_i_s _v_e_r_s_i_o_n _o_f _H_e_x_b_i_n _D_i_s_p_l_a_y_s

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

     Display of hexagonally binned data, as implemented in the 'hexbin'
     packge, under the Trellis framework, with associated utilities. 
     'hexbinplot' is the high level generic function, with the
     '"formula"' method doing the actual work. 'prepanel.hexbinplot'
     and 'panel.hexbinplot' are associated prepanel and panel
     functions.  'hexlegendGrob' produces a suitable legend.

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

     hexbinplot(x, ...)

     ## S3 method for class 'formula':
     hexbinplot(x, data = parent.frame(),
                prepanel = prepanel.hexbinplot,
                panel = if (is.null(groups))
                      panel.hexbinplot else panel.hexpose,
                groups = NULL,
                aspect = "xy",
                trans = NULL,
                inv = NULL,
                colorkey = TRUE,
                ...,
                maxcnt,
                legend = NULL,
                legend.width = TRUE)

     prepanel.hexbinplot(x, y, type = character(0), ...)

     panel.hexbinplot(x, y,
                      xbins = 30,
                      xbnds = c("panel", "data"),
                      ybnds = c("panel", "data"),

                      .prelim, .cpl, .xlim, .ylim, .aspect.ratio,

                      type = character(0),
                      ...,
                      check.erosion = FALSE)

     hexlegendGrob(legend = 1.2,
                   inner = legend / 5,
                   cex.labels = 1,
                   cex.title = 1.2,
                   style = "colorscale",
                   minarea = 0.05, maxarea = 0.8,
                   mincnt = 1, maxcnt,
                   trans = NULL, inv = NULL,
                   colorcut = seq(0, 1, length = 17),
                   density = NULL, border = NULL, pen = NULL,
                   colramp = function(n) { LinGray(n,beg = 90,end = 15) },
                   ...,
                   vp = NULL,
                   draw = FALSE)

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

       x: For 'hexbinplot', the object on which method dispatch is
          carried out.

          For the '"formula"' methods, a formula describing the form of
          conditioning plot.  Formulas that are valid for 'xyplot' are
          acceptable.

          In 'panel.hexbinplot', the x variable. 

       y: In 'panel.hexbinplot', the y variable. 

    data: For the 'formula' method, a data frame containing values for
          any variables in the formula, as well as 'groups' and
          'subset' if applicable ('groups' is ignored by the default
          panel function).  By default the environment where the
          function was called from is used.  

   xbins: number of hexagons covering x values.  The number of y-bins
          depends on this, the aspect ratio, and 'xbnds' and 'ybnds' 

xbnds, ybnds: Numeric vector specifying range of values that should be
          covered by the binning.  In a multi-panel display, it is not
          necessarily a good idea to use the same bounds (which along
          with 'xbins' and the aspect ratio determine the size of the
          hexagons) for all panels.  For example, when data is
          concentrated in small subregions of different panels, more
          detail will be shown by using smaller hexagons covering those
          regions.  To control this, 'xbnds' and 'ybnds' can also be
          character strings '"panel"' or '"data"' (which are not very
          good names and may be changed in future).  In the first case,
          the bounds are taken to be the limits of the panel, in the
          second case, the limits of the data (packet) in that panel. 
          Note that all panels will have the same limits (enough to
          cover all the data) by default if 'relation="free"' in the
          standard trellis argument 'scales', but not otherwise. 

minarea, maxarea, mincnt, maxcnt, trans, inv, colorcut, density,
border, pen, colramp, style: 
          see 'gplot.hexbin' 

prepanel, panel, aspect: See 'xyplot'.  'aspect="fill"' is not allowed.
           The current default of '"xy"' may not always be the best
          choice, often 'aspect=1' will be more reasonable.  

.prelim, .cpl, .xlim, .ylim, .aspect.ratio: for internal use 

colorkey: logical, whether a legend should be drawn.  Currently a
          legend can be drawn only on the right. 

legend.width, legend: width of the legend in inches when 'style' is
          '"nested.lattice"' or '"nested.centroids"'.  The name
          'legend.width' is used to avoid conflict with the standard
          trellis argument 'legend'.  It is possible to specify
          additional legends using the 'legend' or 'key' arguments as
          long as they do not conflict with the hexbin legend (i.e.,
          are not on the right).  

   inner: Inner radius in inches of hexagons in the legend when 'style'
          is '"nested.lattice"' or '"nested.centroids"'.  

cex.labels, cex.title: in the legend, multiplier for numeric labels and
          text annotation respectively 

    type: character vector controlling additional augmentation of the
          display.  A '"g"' in 'type' adds a reference grid, '"r"' adds
          a regression line (y on x), '"smooth"' adds a loess smooth 

check.erosion: ignored. Should not be specified. 

    draw: logical, whether to draw the legend grob.  Useful when
          'hexlegendGrob' is used separately  

      vp: grid viewport to draw the legend in 

     ...: extra arguments, passed on as appropriate.  Arguments to
          'gplot.hexbin', 'xyplot', 'panel.hexbinplot' and
          'hexlegendGrob' can be supplied to the high level
          'hexbinplot' call. 

  groups: 

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

     The panel function 'panel.hexbinplot' creates a hexbin object from
     data supplied to it and plots it using 'grid.hexagons'.  To make
     panels comparable, all panels have the same 'maxcnt' value, by
     default the maximum count over all panels.  This default value can
     be calculated only if the aspect ratio is known, and so
     'aspect="fill"' is not allowed.  The default choice of aspect
     ratio is different from the choice in 'hexbin' (namely, '1'),
     which may sometimes give better results for multi-panel displays. 
     'xbnds' and 'ybnds' can be numeric range vectors as in 'hexbin',
     but they can also be character strings specifying whether all
     panels should have the same bins.  If they are not, then bins in
     different panels could be of different sizes, in which case
     'style="lattice"' and 'style="centroids"' should be interpreted
     carefully.

     The dimensions of the legend and the size of the hexagons therein
     are given in absolute units (inches) by 'legend.width' and 'inner'
     only when 'style' is '"nested.lattice"' or '"nested.centroids"'. 
     For other styles, the dimensions of the legend are determined
     relative to the plot.  Specifically, the height of the legend is
     the same as the height of the plot (the panel and strip regions
     combined), and the width is the minimum required to fit the legend
     in the display.  This is different in some ways from the 'hexbin'
     implementation.  In particular, the size of the hexagons in the
     legend are completely unrelated to the sizes in the panels, which
     is pretty much unavoidable because the sizes need not be the same
     across panels if 'xbnds' or 'ybnds' is '"data"'. The size of the
     hexagons encode information when 'style' is '"lattice"' or
     '"centroids"', consequently a warning is issued when a legend is
     drawn with wither of these styles.

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

     'hexbinplot' produces an object of class '"trellis"'. The
     code{update} method can be used to update components of the object
     and the 'print' method (usually called by default) will plot it on
     an appropriate plotting device.  'hexlegendGrob' produces a
     '"grob"' (grid object).

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

     Deepayan Sarkar deepayan@stat.wisc.edu

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

     'hexbin', 'xyplot'

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

     mixdata <-
         data.frame(x = c(rnorm(5000),rnorm(5000,4,1.5)),
                    y = c(rnorm(5000),rnorm(5000,2,3)),
                    a = gl(2, 5000))
     hexbinplot(y ~ x, mixdata, aspect = 1,
                trans = sqrt, inv = function(x) x^2)
     hexbinplot(y ~ x | a, mixdata)
     hexbinplot(y ~ x | a, mixdata, style = "lattice",
                xbnds = "data", ybnds = "data")
     hexbinplot(y ~ x | a, mixdata, style = "nested.centroids")
     hexbinplot(y ~ x | a, mixdata, style = "nested.centroids",
                border = FALSE, type = c("g", "smooth"))

