KernSur               package:GenKern               R Documentation

_B_i_v_a_r_i_a_t_e _k_e_r_n_e_l _d_e_n_s_i_t_y _e_s_t_i_m_a_t_i_o_n

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

     Compute bivariate kernel density estimate using five parameter
     Gaussian kernels which can also use non equally spaced and
     adaptive bandwidths

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

     KernSur(x, y, xgridsize=100, ygridsize=100, correlation=0, xbandwidth,
     ybandwidth, range.x, range.y, na.rm=FALSE)

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

       x: vector of 'x' values

       y: vector of 'y' values

xgridsize: integer for number of ordinates at which to calculate the
          smoothed estimate: default=100

ygridsize: integer for number of ordinates at which to calculate the
          smoothed estimate: default=100

correlation: 'x,y' correlation, or vector of local correlations:
          default='cor(x,y)'

xbandwidth: value of 'x' window width, or vector of local window
          widths: default='dpik(x)'

ybandwidth: value of 'y' window width, or vector of local window
          widths: default=dpik(y)

 range.x: total range of the estimate in the 'x' dimension, or a vector
          giving the 'x' ordinates: default='range +- 1.5 * mean
          bandwidth'

 range.y: total range of the estimate in the 'y' dimension, or a vector
          giving the 'y' ordinates: default='range +- 1.5 * mean
          bandwidth'

   na.rm: NA behaviour: 'TRUE' drops cases with NA's, 'FALSE' stops
          function with a warning if NA's are detected: default='FALSE'

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

     returns two vectors and a matrix: 

   xvals: vector of ordinates at which the density has been estimated
          in the 'x' dimension

   yvals: vector of ordinates at which the density has been estimated
          in the 'y' dimension

    zden: matrix of density for 'f(x,y)' with dimensions 'xgridsize',
          'ygridsize'

_A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s:

     Written in collaboration with A.M.Pollard
     <a.m.pollard@bradford.ac.uk> with the financial support of the
     Natural Environment Research Council (NERC) grant GR3/11395

_N_o_t_e:

     Slow code suitable for visualisation and display of correlated
     p.d.f, where highly generalised k.p.d.fs are needed - 'bkde2D' is
     much faster when uncorrelated, uniformly grided, single bandwidth,
     k.p.d.fs are required.

     This function doesn't use bins as such, it calculates the density
     at a set of points in each dimension. These points can be thought
     of as 'bin centres' but in reality they're not.

     From version 1.00 onwards a number of improvements have been made:
     NA's are now handled semi-convincingly by dropping if required. A
     multi-element vector of bandwidths associated with each case can
     be sent for either dimension, so it is possible to accept the
     default, give a fixed bandwidth, or a bandwidth associated with
     each case. A multi-element vector of correlations can be sent,
     rather than a single correlation.

     It should be noted that if a vector is sent for correlation, or
     either bandwidth, they must be of the same length as the data
     vectors. Furthermore, vectors which approximate the bin centres,
     can be sent rather than the extreme limits in the range; which
     means that the points at which the density is to be calculated
     need not be uniformly spaced.

     If the default 'bandwidth' is to be used there *must* be at least
     five unique values for in the 'x' and 'y' vectors. If not the
     function will return an error. If you don't have five unique
     values in the vector then send a value, or vector for 'bandwidth'

     The number of ordinates defaults to the length of 'range.x' if
     'range.x' is a vector of ordinates, otherwise it is 'xgridsize',
     or 100 if that isn't specified.

     Finally, the various modes of sending parameters can be mixed, ie:
     the extremes of the range can be sent to define the range for 'x',
     but a multi-element vector could be sent to define the ordinates
     in the 'y' dimension, or, a vector could be sent to describe the
     bandwidth for each case in the 'x' direction, and a single-element
     vector defines all bandwidths in the 'y'.

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

     David Lucy <dlucy@maths.ed.ac.uk> 
      Robert Aykroyd <robert@amsta.leeds.ac.uk><URL:
     http://www.amsta.leeds.ac.uk/~robert/>

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

     Robertson, I. Lucy, D. Baxter, L. Pollard, A.M. Aykroyd, R.G.
     Carter, A.H.C. Switsur, V.R. and Waterhouse, J.S.(1999) A kernel
     based Bayesian approach to climatic reconstruction. _Holocene_
     *9*(4): 495-500

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

     'KernSur' 'per'  'density' 'hist' 'bkde' 'bkde2D' 'dpik'

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

     x <- c(2,4,6,8)                         # make up some x-y data
     y <- x 

     # calculate and plot a surface with zero correlation based on above data
     op <- KernSur(x,y, xgridsize=50, ygridsize=50, correlation=0, 
             xbandwidth=1, ybandwidth=1, range.x=c(0,10), range.y=c(0,10))
     image(op$xvals, op$yvals, op$zden, col=terrain.colors(100), axes=TRUE)
     contour(op$xvals, op$yvals, op$zden, add=TRUE)
     box()

     # re-calculate and re-plot the above using a 0.8 correlation
     op <- KernSur(x,y, xgridsize=50, ygridsize=50, correlation=0.8,
              xbandwidth=1, ybandwidth=1, range.x=c(0,10), range.y=c(0,10))
     image(op$xvals, op$yvals, op$zden, col=terrain.colors(100), axes=TRUE)
     contour(op$xvals, op$yvals, op$zden, add=TRUE)
     box()

     # calculate and plot a surface of the above data with an ascending
     # correlation and bandwidths and a vector of equally spaced ordinates
     bands <- c(1,1.1,1.2,1.3)
     cors <- c(0,-0.2,-0.4,-0.6)
     rnge.x <- seq(from=0, to=10, length=100)

     op <- KernSur(x,y, xgridsize=50, ygridsize=50, correlation=cors, 
             xbandwidth=bands, ybandwidth=bands, range.x=rnge.x, range.y=c(0,10))
     image(op$xvals, op$yvals, op$zden, col=terrain.colors(100), axes=TRUE)
     contour(op$xvals, op$yvals, op$zden, add=TRUE)
     box()

