NNCH               package:adehabitat               R Documentation

_N_e_a_r_e_s_t _N_e_i_g_h_b_o_r _C_o_n_v_e_x _h_u_l_l

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

     'NNCH' computes the home range of several animals using the
     nearest neighbor convex hull method (Getz and Wilmers, 2004).
      'plot.NNCH' gives a graphical display of the estimation.
      'NNCH.area' is used for home-range size estimation.
      'neighNNCH' is used to determine the optimum number of neighbors
     (plots the home-range size estimated to a given percentage level
     according to the number neighbors used for the estimation).
      'getverticesNNCH' is used to store the limits of the home ranges.
      'plot.NNCHver' displays the limits of the home ranges (but see
     the section "note").
      'NNCH.rast' is used to convert the home range to raster.

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

     NNCH(xy, id = NULL, k = 10, unin = c("m", "km"), unout = c("ha", "km2", "m2"))
     plot.NNCH(x, which = names(x), add.points = TRUE, pch = 21,
               bgpts = "white", colpts = "black",
               cex = 0.7, add = FALSE, same4all = TRUE,
               border = NA, ...)
     NNCH.area(x, percent = c(95,90,80,70,60,50,40,30,20,10))
     neighNNCH(xy, id = NULL, rangek, percent = 95,
               unin = c("m", "km"), unout = c("ha", "km2", "m2"))
     plot.ngNNCH(x, ...)
     getverticesNNCH(x, percent = 95)
     plot.NNCHver<-function(x, which = names(x),
                            colpol = NA,
                            colborder = rep("black", length(x)),
                            lwd = 2, add = FALSE, ...)
     NNCH.rast(y, w)

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

      xy: a data frame containing the coordinates of the relocation of
          the monitored animals

      id: a factor giving the identity of the animal for each
          relocation

       k: the number of neighbors to take into account in the
          estimation

    unin: the units of the relocations coordinates.  Either '"m"'
          (default) for meters 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)

       x: an object of class "'NNCH'".  For 'plot.NNCHver', an object
          of class 'NNCHver' returned by the function 
          'getverticesNNCH'.  For 'plot.ngNNCH', an object of class
          'ngNNCH' returned by the function 'neighNNCH'

   which: a vector of character strings, indicating the names of the
          animals to be plotted

add.points: logical.  'TRUE' if the relocations are to be plotted

     pch: if 'add.points' is 'TRUE', the size of the points to be used
          for the plot of the relocations (see 'par')

   bgpts: if 'add.points' is 'TRUE', the background color to be used
          for the plot of the relocations (see 'par')

  colpts: if 'add.points' is 'TRUE', the color of the points to be used
          for the plot of the relocations (see 'par')

     cex: if 'add.points' is 'TRUE', the size of the points to be used
          for the plot of the relocations (see 'par')

     add: logical.  Whether the home ranges should be displayed on a
          previous plot

  border: The color of the border of the polygons. 'NA' if a border is
          not required

same4all: logical.  If 'TRUE', the plot displaying the home ranges has
          the same X and Y limits for all animals

     ...: additional arguments to be passed to the generic function
          'plot' 

 percent: for 'NNCH.area', a vector of percentage levels for home-range
          size estimation.  For 'getverticesNNCH', one value giving the
          percentage level for the home range estimation. 

  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

       w: an object of class 'asc' or 'kasc'

  rangek: a vector giving several numbers of neighbors to test

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

     'NNCH' returns a list of class 'NNCH'.
      'NNCH.area' returns an object of class 'hrsize'.
      'neighNNCH' returns a matrix of class 'ngNNCH'.
      'getverticesNNCH' returns an object of class 'NNCHver'.
      'NNCH.rast' returns a raster map of class 'asc' or 'kasc'.

_W_a_r_n_i_n_g:

     These functions require the package 'gpclib'.

_N_o_t_e:

     The NNCH method can lead to home ranges with holes.  In other
     words, inside the outer limits of the home ranges there are some
     areas that are not used by the animals.  Due to the presence of
     these holes, it is not possible to stores the home ranges with the
     class "area", as for the minimum convex polygon (see '?mcp') or
     the kernel estimator (see '?kernelUD').  Therefore, the functions
     of the package gpclib are used here to deal with this kind of home
     ranges. Note, however, that when the home ranges contain holes,
     the function 'plot.NNCHver' does not displays the holes correctly
     (filled in with the specified color).

     The home range can be estimated at different percentage levels. 
     These levels correspond the percentage of relocations included
     within the limits of the home range.  Note, however, that a given
     percentage level can correspond to a collection of different home
     ranges (see example below).  Here, we define the NNCH home-range
     as the _larger_ area including the specified percentage.

     Finally, note that this function is very long with large datasets.

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

     Clment Calenge calenge@biomserv.univ-lyon1.fr

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

     Getz, W.M. & Wilmers, C.C. (2004). A local nearest-neighbor
     convex-hull construction of home ranges and utilization
     distributions. _Ecography_, *in press*.

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

     'plot.hrsize' to display the home-range size according to the
     percentage level of the estimation.

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

     ## Not run: 

     ## Can also be used to analyse a point pattern
     ## For example, locations of chamois in
     ## the Chartreuse mountains (French Alps)

     data(chamois)
     xy <- chamois$locs

     ## choice of the number of neighbors
     ## Warning: this command can be very long (more than two minutes)
     u <- neighNNCH(xy, rangek = 5:30)
     plot(u)

     ## 13 and 20 neighbours seem to be a good choice
     ## Estimates the home range levels
     (aa <- NNCH(xy, k = 13))
     plot(aa)

     ## plot of the home-range size
     plot(NNCH.area(aa))

     ## gets the home range contour
     cont <- getverticesNNCH(aa)
     plot(cont)

     ## rasterizes these contours
     sl <- getkasc(chamois$map, "Slope")
     mm <- NNCH.rast(cont, sl)
     image(mm)

     ## Note that two different sets of polygons can include
     ## the same percentage of relocation
     aa[[1]]$area[97:105,]

     ## For example, the same percentage of relocations is
     ## included within the limits of the two home ranges
     ## (91.92 percent of the localisations) 
     opar <- par(mfrow=c(1,2))
     plot(aa[[1]]$polygons[[103]],
          poly.args = list(lwd = 2))
     points(xy, pch = 16, cex = 0.5)

     plot(aa[[1]]$polygons[[98]],
          poly.args = list(lwd = 2))
     points(xy, pch=16, cex = 0.5)
     par(opar)
     ## only the left-hand plot is considered as an
     ## home range estimation (the larger one)

     ## End(Not run)

