kernelUD             package:adehabitat             R Documentation

_E_s_t_i_m_a_t_i_o_n _o_f _K_e_r_n_e_l _H_o_m_e-_R_a_n_g_e

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

     'kernelUD' is used to estimate the utilization distribution (UD)
     of animals monitored by radio-tracking, with the classical kernel
     method.
      'getvolumeUD' and 'kernel.area' provide utilities for home-range
     size estimation.
      'getverticeshr' stores the home range contour as objects of class
     'area' in a list of class 'kver', with one component per animal.
      'plot.kver' is used to display these home-range contours.
      'kernelbb' is used to fit an utilization distribution using the
     brownian bridge approach of the kernel method (for autocorrelated
     relocations; Bullard, 1991).

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

     kernelUD(xy, id = NULL, h = "href", grid = 40, same4all = FALSE,
              hlim = c(0.1, 1.5), kern = "bivnorm")
     print.khr(x, ...)
     image.khr(x, axes = FALSE, mar = c(0,0,2,0),
               addcontour = TRUE, addpoints = TRUE, ...)
     plotLSCV(x)
     getvolumeUD(x)
     kernel.area(xy, id, h = "href", grid=40,
                 same4all = FALSE, hlim = c(0.1,1.5), kern = "bivnorm",
                 levels = seq(20,95, by = 5),
                 unin = c("m", "km"),
                 unout = c("ha", "km2", "m2"))
     getverticeshr(x, lev = 95)
     plot.kver(x, which = names(x), colpol=rainbow(length(which)),
               colborder=rep("black", length(which)), lwd = 2,
               add=FALSE, ...)
     kernelbb(tr, sig1, sig2, grid = 40, same4all=FALSE, byburst=FALSE)

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

      xy: a data frame with two columns (x and y coordinates of the
          animal relocations)

      id: an optional factor giving the animals identity associated to
          'xy'

       h: a character string or a number.  If 'h' is set to '"href"',
          the ad hoc method is used for the smoothing parameter (see
          details).  If 'h' is set to  '"LSCV"', the least-square cross
          validation method is used. Note that '"LSCV"' is not
          available if 'kern = "epa"'.  Alternatively, 'h' may be set
          to any given numeric value

    grid: a number giving the size of the grid on which the UD should
          be estimated.  Alternatively, this parameter may be an object
          of class 'asc' (see examples)

same4all: logical. If 'TRUE', the same grid is used for all animals. 
          If 'FALSE', one grid per animal is used

    hlim: a numeric vector of length two.  If 'h = "LSCV"', the
          function minimizes the cross-validation criterion for values
          of h ranging from 'hlim[1]*href' to 'hlim[2]*href', where
          'href' is the smoothing parameter computed with the ad hoc
          method (see below)

    kern: a character string.  If '"bivnorm"', a bivariate normal
          kernel is used.  If '"epa"', an Epanechnikov kernel is used.

       x: an object of class 'khr' returned by 'kernelUD'. For
          'plot.kver', an object of class 'kver' returned by
          'getverticeshr' 

   which: a vector of character indicating the polygons to be plotted

  colpol: a vector of the color for filling the polygon.  The default,
          'NA', is to leave polygons unfilled 

colborder: a vector of the color to draw the border.  The default.  Use
          'border = NA' to omit borders

     lwd: the border width, a *positive* number

     add: logical. if 'TRUE', the polygons are added to a previous plot

    axes: logical.  Whether the axes are to be plotted

     mar: the margin parameter (see 'help(par)')

addcontour: logical. if 'TRUE', contours are drawn on the graphics

addpoints: logical. if 'TRUE', the animal relocations are drawn on the
          graphics

  levels: a vector of percentage levels for home-range size estimation

    unin: the units of the relocations coordinates.  Either '"m"' for
          meters (default) or '"km"' for kilometers

   unout: the units of the output areas.  Either '"m2"' for square
          meters, '"km2"' for square kilometers or '"ha"' for hectares
          (default)

     lev: the percentage level for home range contour estimation.

      tr: an object of class 'traj'.

    sig1: first smoothing parameter for the brownian bridge method
          (related to the imprecision of the relocations).

    sig2: second smoothing parameter for the brownian bridge method
          (related to the speed of the animals).

 byburst: logical. Whether the brownian bridge estimation should be
          done by burst.

     ...: additionnal parameters to be passed to the generic functions
          'print' and 'image'

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

     The Utilization Distribution (UD) is the bivariate function giving
     the probability density that an animal is found at a point
     according to its geographical coordinates.  Using this model, one
     can define  the home range as the minimum area in which an animal
     has some specified probability of being located. The functions
     used here correspond to the approach described in Worton (1995).

     The kernel method has been recommended by many authors for the
     estimation of the utilization distribution (e.g. Worton, 1989,
     1995). The default method for the estimation of the smoothing
     parameter is the _ad hoc_ method, i.e. for a bivariate normal
     kernel

                          h = Sigma*n^(-1/6)

     where 

                      Sigma = 0.5*(sd(x)+sd(y))

     which supposes that the UD is bivariate normal.  If an
     Epanechnikov kernel is used, this value is multiplied by 1.77
     (Silverman, 1986, p. 86). Alternatively, the smoothing parameter h
     may be computed by Least Square Cross Validation (LSCV).  The
     estimated value then minimizes the Mean Integrated Square Error
     (MISE), i.e. the difference in volume between the true UD and the
     estimated UD.  Note that the cross-validation criterion cannot be
     minimized in some cases.  According to Seaman and Powell (1998)
     _"This is a difficult problem that has not been worked out by
     statistical theoreticians, so no definitive response is available
     at this time"_ (see Seaman and Powell, 1998 for further details
     and tricky solutions).  'plotLSCV' allows to have a diagnostic of
     the success of minimization of the cross validation criterion
     (i.e. to know whether the minimum of the CV criterion occurs
     within the scanned range).  Finally, the UD is then estimated over
     a grid.

     The default kernel is the bivariate normal kernel, but the
     Epanechnikov kernel, which requires less computer time is also
     available for the estimation of the UD. 

     The function 'getvolumehr' modifies the UD component of the object
     passed as argument, so that the contour of the UD displayed by the
     functions 'contour' and 'image.khr' corresponds to the different
     percentage levels of home-range estimation (see examples).  In
     addition, this function is used in the function 'kernel.area', to
     compute the home-range size.  Note, that the function
     'plot.hrsize' (see the help page of this function) can be used to
     display the home-range size estimated at various levels.

     The function 'kernelbb' uses the brownian bridge approach to
     estimate the UD with autocorrelated relocations (Bullard, 1991).
     Instead of simply smoothing the relocation pattern, it takes into
     account the fact that between two successive relocations r1 and
     r2, the animal has moved through a connected path, which is not
     necessarily linear.  A brownian bridge estimates the density of
     probability that this path passed through any point of the study
     area, given that the animal was located at the point r1 at time t1
     and at the point r2 at time t2, with a certain amount of
     inaccuracy (see Examples).  Brownian bridges are placed over the
     different sections of the traject, and these functions are then
     summed over the area.  The brownian bridge approach therefore
     smoothes a trajectory.

     The brownian bridge estimation relies on two smoothing parameters,
     'sig1' and 'sig2'.  The parameter 'sig1' is related to the speed
     of the animal, and describes how far from the line joining two
     successive relocations the animal can go during one time unit
     (here the time is measured in second). The larger this parameter
     is, and the more wiggly the trajectory is likely to be. The
     parameter 'sig2' is equivalent to the parameter  'h' of the
     classical kernel method: it is related to the inaccuracy of the
     relocations (See examples for an illustration of the smoothing
     parameters).

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

     The class 'khr' is a class grouping three sub-classes, 'khrud',
     'kbbhrud' and 'khrudvol': 'kernelUD' returns a list of the class
     'khrud'.  This list has one component per animal (named as the
     levels of argument 'id'). Each component is itself a list, with
     the following sub-components:  

      UD: an object of class 'asc', with the values of density
          probability in each cell of the grid

       h: if 'LSCV' is not used, the value of the smoothing parameter. 
          if 'LSCV' is used, a list with three components:  .in +5

     '_C_V' the results of the cross-validation procedure. The first 
          column contains the sequence of values tested for the
          smoothing  parameter, and the second column contains the
          value of the cross-validation criterion.

     '_c_o_n_v_e_r_g_e_n_c_e' TRUE if the LSCV succeeds (i.e. if the optimum
          smoothing parameter have been found by the procedure), FALSE
          otherwise.

     '_h' the value of the smoothing parameter used in UD estimation.

    locs: The relocations used in the estimation procedure.

   hmeth: The argument 'h' of the function kernelUD


     'kernelbb' returns an object of class 'kbbhrud', with the same
     components as lists of class 'khrud'.  

     'getvolumeUD' returns a list of class 'khrvol', with the same
     components as lists of class 'khrud'.  

     'kernel.area' returns a data frame of subclass '"hrsize"', with
     one column per animal and one row per level of estimation of the
     home range.

     'getverticeshr' returns an object of class 'kver'.

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

     Clment Calenge calenge@biomserv.univ-lyon1.fr

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

     Bullard, F. (1991) _Estimating the home range of an animal: a
     Brownian bridge approach_. Master of Science, University of North
     Carolina, Chapel Hill.

     Silverman, B.W. (1986) _Density estimation for statistics and data
     analysis_. London: Chapman & Hall.

     Worton, B.J. (1989) Kernel methods for estimating the utilization
     dirstibution in home-range studies. _Ecology_, *70*, 164-168.

     Worton, B.J. (1995) Using Monte Carlo simulation to evaluate
     kernel-based home range estimators. _Journal of Wildlife
     Management_, *59*,794-800.

     Seaman, D.E. and Powell, R.A. (1998) _Kernel home range estimation
     program (kernelhr)_. Documentation of the program. <URL:
     ftp://ftp.im.nbs.gov/pub/software/CSE/wsb2695/KERNELHR.ZIP>.

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

     'import.asc' for additionnal informations on objects of class
     'asc',  'mcp' for estimation of home ranges using the minimum
     convex polygon, and for help on the function 'plot.hrsize'.

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

     data(puechabon)
     loc <- puechabon$locs[, c("X", "Y")]
     id <- puechabon$locs[, "Name"]

     ## Estimation of UD for the four animals
     ud <- kernelUD(loc, id)
     ud

     image(ud) ## Note that the contours
               ## corresponds to values of probability density
     udvol <- getvolumeUD(ud)
     image(udvol)
     ## Here, the contour corresponds to the
     ## home ranges estimated at different probability
     ## levels (i.e. the contour 90 corresponds to the 90 percent
     ## kernel home-range)
     ## udvol describes, for each cell of the grid,
     ## the smaller home-range to which it belongs 

     ## Calculation of the 95 percent home range
     ver <- getverticeshr(ud, 95)
     elev <- getkasc(puechabon$kasc, "Elevation") # Map of the area
     image(elev)
     plot(ver, add=TRUE)
     legend(696500, 3166000, legend = names(ver), fill = rainbow(4))

     ## Example of estimation using LSCV
     udbis <- kernelUD(loc, id, h = "LSCV")
     image(udbis)

     ## Compare the estimation with ad hoc and LSCV method
     ## for the smoothing parameter
     (cuicui1 <- kernel.area(loc, id)) ## ad hoc
     plot(cuicui1)
     (cuicui2 <- kernel.area(loc, id, h = "LSCV")) ## LSCV
     plot(cuicui2)

     ## Diagnostic of the cross-validation
     plotLSCV(udbis)

     ## Use of the same4all argument: the same grid
     ## is used for all animals
     udbis <- kernelUD(loc, id, same4all = TRUE)
     image(udbis)

     ## And finally, estimation of the UD on a map
     ## (e.g. for subsequent analyses on habitat selection)
     elev <- getkasc(puechabon$kasc, "Elevation")
     opar <- par(mfrow = c(2, 2), mar = c(0, 0, 2, 0))
     cont <- getcontour(elev)

     for (i in 1:length(udbis)) {
        image(elev, main = names(udbis)[i], axes = FALSE)
        points(udbis[[i]]$locs, pch = 21, bg = "white", col = "black")
     }

     ## Measures the UD in each pixel of the map
     udbis <- kernelUD(loc, id, grid = elev)
     opar <- par(mfrow = c(2, 2), mar = c(0, 0, 2, 0))
     for (i in 1:length(udbis)) {
       image(udbis[[i]]$UD, main = names(udbis)[i], axes = FALSE)
       box()
       polygon(cont[, 2:3])
     }
     par(opar)



     ###############################################
     ###############################################
     ###############################################
     ###
     ###         Kernel estimation: a brownian
     ###               bridge approach

     ## Not run: 

     ## loads the data
     data(puechcirc)

     ## gets one circuit
     x <- getburst(puechcirc, burst = "CH930824")

     ## fits the home range
     (tata <- kernelbb(x, 10, 10, same4all = TRUE))
     image(tata)
     lines(x$x, x$y, lwd = 2, col = "red")

     ## Image of a brownian bridge. Fit with two relocations:
     fac <- factor(c("a", "a"))
     xx <- c(0,1)
     yy <- c(0,1)
     date <- c(0,1)
     class(date) <- c("POSIXt", "POSIXct")
     tr <- as.traj(fac, data.frame(x = xx,y = yy), date)

     ## Use of different smoothing parameters
     sig1 <- c(0.05, 0.1, 0.2, 0.4, 0.6)
     sig2 <- c(0.05, 0.1, 0.2, 0.5, 0.7)

     y <- list()
     for (i in 1:5) {
       for (j in 1:5) {
          k <- paste("s1=", sig1[i], ", s2=", sig2[j], sep = "")
          y[[k]]<-kernelbb(tr, sig1[i], sig2[j])[[1]]$UD
        }
      }

     ## Displays the results
     opar <- par(mar = c(0,0,2,0), mfrow = c(5,5))
     foo <- function(x)
        {
          image(y[[x]], main = names(y)[x], axes = F)
          points(tr[,c("x","y")], pch = 16, col = "red")
        }
     lapply(1:length(y), foo)

     par(opar)

     ## End(Not run)

