hexagons               package:hexbin               R Documentation

_A_d_d _H_e_x_a_g_o_n _C_e_l_l_s _t_o _P_l_o_t

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

     Plots cells in an hexbin object.  The function distinquishes among
     counts using 5 different styles. This function is the hexagon
     plotting engine called from 'plot.hexbin()' and 'hex.legend()'.

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

     hexagons(dat, style = "colorscale", minarea = 0.05, maxarea = 0.8, mincnt = 1,
              maxcnt = max(dat$cnt), trans = NULL, colorcut, density = -1,
              border = FALSE, pen=NULL,
              colramp = function(n){LinGray(n,beg=90,end=15)},
              verbose = getOption("verbose"))

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

     dat: an object of class 'hexbin', see 'hexbin'.

   style: character specifying the type of plotting; must be one of
          ("grayscale","lattice","centroids","nested.lattice","nested.c
          entroids").

 minarea: The fraction of cell area for the lowest count.

 maxarea: The fraction of the cell area for the largest count

  mincnt: Cells with smaller counts are not shown

  maxcnt: Cells with large counts are not shown

   trans: A transformation for the counts such as sqrt()

colorcut: A vector of values covering [0, 1] which determine hexagon
          color classes boundaries or hexagon size boundaries.

 density: Polygon() fill argument.  0 causes the polygon not to be
          filled.

  border: Polygon() border argument.  Draw the border for each hexagon

     pen: Polygon() col argument. Determines the color with which the
          polygon will be filled

 colramp: A function accepting n as its argument and returning n
          colors. n is determined 

 verbose: logical indicating if some diagnostic output should happen.

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

     The five plotting styles have the following effect:

     '_s_t_y_l_e="_l_a_t_t_i_c_e"' _o_r '"_c_e_n_t_r_o_i_d_s"' Plots the hexagons in different
          sizes based on counts.  The '"lattice"' version centers the
          hexagons at the cell centers whereas '"centroids"' moves
          centers the hexagons close to the center of mass for the
          cells.  In all cases the hexagons will not plot outside the
          cell unless 'maxarea > 1'.  Counts are rescaled into the
          interval [0,1] and colorcuts determine the class boundaries
          for sizes and counts. The pen argument for this style should
          be a single color or a vector of colors of 'length(bin$cnt)'.

     '_s_t_y_l_e="_c_o_l_o_r_s_c_a_l_e"' Counts are rescaled into the interval [0,1]
          and colorcuts determines the class boundaries for the color
          classes. For this style the function specified in coloramp is
          used to define the n colors for the n+1 color cuts. In for
          this style the pen argument is ignored.


     '_s_t_y_l_e="_n_e_s_t_e_d._l_a_t_t_i_c_e"' _a_n_d '"_n_e_s_t_e_d._c_e_n_t_r_o_i_d_s"' Counts are
          partioned into classes by power of 10.  The encoding nests
          hexagon size within powers of 10 color contours.

          If the pen argument is used it should be a matrix of colors
          with 2 columns and either 'ceiling(log10(max(bin$cnt)))' or
          'length(bin$cnt)' rows. The default uses the R color palatte
          so that pens numbers 2-11 determine colors for completely
          filled cell Pen 2 is the color for 1's, Pen 3 is the color
          for 10's, etc. Pens numbers 12-21 determine the color of the
          foreground hexagons. The hexagon size shows the relative
          count for the power of 10. Different color schemes give
          different effects including 3-D illusions

     _Hexagon size encoding 'minarea' and 'maxarea'_ determine the area
     of the smallest and largest hexagons plotted.  Both are expressed
     fractions of the bin cell size.  Typical values might be .04 and
     1.  When both values are 1, all plotted hexagons are bin cell
     size, if 'maxarea' is greater than 1 than hexagons will overlap.
     This is sometimes interesting with the lattice and centroid
     styles.

     _Count scaling_

     'relcnt <- (trans(cnt)-trans(mincnt)) /
     (trans(maxcnt)-trans(mincnt))' 
      'area <- minarea + relcnt*maxarea'

     By default the transformation 'trans()' is the identity function. 
     The legend routine requires the transformation inverse for some
     options.

     _Count windowing 'mincnt' and 'maxcnt'_ Only routine only plots
     cells with cnts in [mincnts,   maxcnts]

_S_I_D_E _E_F_F_E_C_T_S:

     Adds hexagons to the plot.

_N_o_t_e:

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

     Dan Carr <dcarr@voxel.galaxy.gmu.edu> ported and extended by
     Nicholas Lewin-Koh <nikko@hailmail.net>

_R_e_f_e_r_e_n_c_e_s:

     Carr, D. B. (1991) Looking at Large Data Sets Using Binned Data
     Plots, pp. 7-39 in _Computing and Graphics in Statistics_; Eds. A.
     Buja and P. Tukey, Springer-Verlag, New York.

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

     'hexbin', 'smooth.hexbin', 'erode.hexbin', 'hcell', 'hcell2xy',
     'plot.hexbin', 'hboxplot', 'hdiffplot', 'hmatplot', 'hex.legend'

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

     #  A quick example

     set.seed(506)
     x <- rnorm(10000)
     y <- rnorm(10000)

     # bin the points
     bin <- hexbin(x,y)

     ## setup coordinate system:
     plot(bin$xbnd, bin$ybnd, type="n", main = "Bivariate rnorm(10000)", asp=1)
     hexagons(bin)

     #  A better approach uses plot.hexbin
     #   and controls the plot shape
     plot(bin)

     # A mixture distribution
     x <- c(rnorm(5000),rnorm(5000,4,1.5))
     y <- c(rnorm(5000),rnorm(5000,2,3))
     bin <- hexbin(x,y)

     # Show color control and overplotting of hexagons
     plot(bin$xbnd, bin$ybnd, type="n", main = "Bivariate mixture (10000)", asp=1)
     hexagons(bin, style= "lattice", border = gray(.1), pen = gray(.6),
              minarea = .1, maxarea = 1.5)

     # And if we had all the information...
     if(require(gpclib)){
       h1<-chull(x[1:5000],y[1:5000])
       h2<-chull(x[5001:10000],y[5001:10000])
       h2<-h2+5000
       h1<-as(cbind(x[1:5000],y[1:5000])[h1, ], "gpc.poly")
       h2<-as(cbind(x,y)[h2, ], "gpc.poly")
       plot(bin$xbnd, bin$ybnd, type="n", main = "Bivariate mixture (10000)", asp=1)
       plot(h1,poly.args = list(col ="#CCEBC5"),add = TRUE)
       plot(h2,poly.args = list(col ="#FBB4AE"),add = TRUE)
       plot(intersect(h1, h2), poly.args = list(col = 2), add = TRUE)  
       hexagons(bin, style= "lattice", border = gray(.1), pen = gray(.6),
                minarea = .1, maxarea = 1.5)
     }

