NNCH {adehabitat} | R Documentation

## Nearest Neighbor Convex hull

### Description

`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.

### Usage

    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)

### Arguments

`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

### Value

`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`.

### Warning

These functions require the package `gpclib`.

### Note

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.

### Author(s)

Clément Calenge calenge@biomserv.univ-lyon1.fr

### References

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

### See Also

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

### Examples

    ## 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)

[Package adehabitat version 1.3 Index]