kernelkc: Kernel Smoothing in Space and Time of the Animals' Use of...
In ClementCalenge/adehabitat: Analysis of Habitat Selection by Animals

Description Usage Arguments Details Value Author(s) References See Also Examples

These functions estimate the utilization distribution (UD) in space and time of animals monitored using radio-telemetry, using the product kernel estimator advocated by Keating and Cherry (2009).

Note that this approach has also been useful for the analysis of recoveries in programs involving ringed birds (Calenge et al. in prep., see section examples below).

kernelkc estimate the UD of several animals from an object of class ltraj.
kernelkcbase estimate one UD from a data frame with three columns indicating the spatial coordinates and associated timing.
exwc allows to search for the best value of the time smoothing parameter in the case where the time is considered as a circular variable (see details).
getvolumeUDk and getvolumeUDs provide utilities for home-range estimation.
getverticeshrk and getverticeshrs store the home range contours.

kernelkc(tr, h, tcalc, t0, grid = 40, circular = FALSE,
         cycle = 24 * 3600, same4all = FALSE,
         byburst = FALSE, extent = 0.5)

kernelkcbase(xyt, h, tcalc, t0, grid=40, circular=FALSE,
             cycle=24*3600, extent=0.5)

getvolumeUDk(kc)
getvolumeUDs(asc)

getverticeshrk(kc, lev = 95)
getverticeshrs(ascv, lev = 95)

exwc(hv)

`tr`	an object of class `ltraj`
`xyt`	a data frame with three columns indicating the x and y coordinates, as well as the timing of the relocations.
`kc`	an object of class `kernelkco` returned by the function `kernelkc`
`asc`	an object of class `asc` returned by the function `kernelkcbase`
`ascv`	an object of class `asc` returned by the function `getvolumeUDs`
`lev`	the percentage level for home range contour estimation.
`h`	a numeric vector with three elements indicating the value of the smoothing parameters: the first and second elements are the smoothing parameters of the X and Y coordinates respectively, the third element is the smoothing parameter for the time dimension. If `circular=TRUE` it should be a smoothing parameter in the interval 0-1 (see details). If `circular=FALSE` this smoothing parameter should be given in seconds.
`tcalc`	the time at which the UD is to be estimated
`t0`	if `circular=TRUE`, this parameter indicates the time at which the time cycle begins (see examples).
`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`, or a list of objects of class `asc`, with named elements corresponding to each level of the burst/id
`circular`	logical. Indicates whether the time should be considered as a circular variable (e.g., the 31th december 2007 is considered to be one day before the 1st january 2007) or not (e.g., the 31th december 2007 is considered to be one year after the 1st january 2007).
`cycle`	if `circular=TRUE`, the duration of the time cycle. for `kernelkc`, it should be given in seconds, and for `kernelkcbase`, in the units of the data (the units of the third column of `xyt`).
`same4all`	logical. If `TRUE`, the same grid is used for all levels of id/burst. If `FALSE`, one grid per id/burst is used.
`byburst`	logical. Indicates whether one UD should be estimated by burst of `tr`, or whether the data should be pooled across all bursts of each value of id in `tr`
`extent`	a value indicating the extent of the grid used for the estimation (the extent of the grid on the abscissa is equal to `(min(xy[,1]) + extent * diff(range(xy[,1])))`).
`hv`	a value of smoothing parameter for the time dimension.
`...`	additional arguments to be passed to the function `contour`.

Keating and Cherry (in press) advocated the estimation of the UD in time and space using the product kernel estimator. These functions implement exactly this methodology.

For the spatial coordinates, the implemented kernel function is the biweight kernel.

Two possible approaches are possible to manage the time in the estimation process: (i) the time may be considered as a linear variable (e.g., the 31th december 2007 is considered to be one day before the 1st january 2007), or (ii) the time may be considered as a circular variable (e.g., the 31th december 2007 is considered to be one year after the 1st january 2007).

If the time is considered as a linear variable, the kernel function used in the estimation process is the biweight kernel. If the time is considered as a circular variable, the implemented kernel is the wrapped Cauchy distribution (as in the article of Keating and Cherry). In this latter case, the smoothing parameter should be chosen in the interval 0-1, with a value of 1 corresponding to a stronger smoothing.

These functions can only be used on objects of class "ltraj", but the estimation of the UD in time and space is also possible with other types of data (see the help page of kernelkcbase). Note that both kernelkc and kernelkcbase return conditional probability density function (pdf), i.e. the pdf to relocate an animal at a place, given that it has been relocated at time tcalc (i.e. the volume under the UD estimated at time tcalc is equal to 1 whatever tcalc).

The functions getvolumeUDk and getvolumeUDs modifies the UDs, so that the contour of the UD displayed by the function contour corresponds to the different percentage levels of home-range estimation (see examples).

The function exwc draws a graph of the wrapped Cauchy distribution for the chosen h parameter (for circular time), so that it is possible to make one's mind concerning the weight that can be given to the neighbouring points of a given time point. Note that although Keating and Cherry (in press) advocated the use of an automatic algorithm to select "optimal" values for the smoothing parameter, it is not implemented in adehabitat. Indeed, different smoothing parameters may allow to identify patterns at different scales, and we encourage the user to try several values before subjectively choosing the value which allows to more clearly identify the patterns of the UD.

kernelkc returns a list of class "kernelkco" containing objects of class asc, mapping one estimate of the UD per burst or id (depending on the value of the parameter byburst).

getvolumekc returns a list of class "kernelkcov" containing objects of class asc, mapping the volume under the UD for each burst or id.

kernelkcbase returns an object of class "asc" mapping the estimated UD. The volume under the UD can be computed using the function getvolumeUDs.

getverticeshrk stores the home range contour as objects of class area in a list of class kver, with one component per burst/id.

getverticeshrs stores the home range contour as an object of class area.

Clement Calenge clement.calenge@oncfs.gouv.fr

Keating, K. and Cherry, S. (in press) Modeling utilization distributions in space and time. Ecology, in press.

Calenge, C., Guillemain, M., Gauthier-Clerc, M. and Simon, G. in prep. A new exploratory approach to the study of the spatio-temporal distribution of ring recoveries - the example of Teal (Anas crecca) ringed in Camargue, Southern France.

as.ltraj for additional information on objects of class ltraj, kernelUD for the "classical" kernel home range estimates.

## Not run: 


################################################
##
## Illustrates the analysis of recoveries of
## ringed data

data(teal)
head(teal)

## compute the sequence of dates at which the
## probability density function (pdf) of recoveries is to be estimated

vv <- seq(min(teal$date), max(teal$date), length=50)
head(vv)

## The package "maps" should be installed for the example below
library(maps)


re <- lapply(1:length(vv), function(i) {

             ## Estimate the pdf. We choose a smoothing parameter of
             ## 2 degrees of lat-long for X and Y coordinates,
             ## and of 2 months for the time
             uu <- kernelkcbase(teal, c(2.5,2.5,2*30*24*3600), tcalc =
                                vv[i], grid=100, extent=0.1)

             ## now, we show the result
             ## potentially, we could type
             ##
             ## jpeg(paste("prdefu", i, ".jpg", sep=""))
             ##
             ## to store the figures in a file, and then to build a
             ## movie with the resulting files:
             ##

             image(uu, main=vv[i])

             ## highlight the area on which there is a probability
             ## equal to 0.95 to recover a bird
             hh <- getvolumeUDs(uu)

             contour(hh, levels=95, col="red",
                     drawlabels=FALSE, add=TRUE, lwd=2)

             ## The map:
             map(xlim=c(-20,70), ylim=c(30,80), add=TRUE)

             ## and if we had typed jpeg(...) before, we have to type
             ## dev.off()
             ## to close the device. When we have finished this loop
             ## We could combine the resulting files with imagemagick
             ## (windows) or mencoder (linux)
             })




################################################
##
## Illustrates how to explore the UD in time and
## space with the bear data

data(bear)

## compute the sequence of dates at which the UD is to be
## estimated
vv <- seq(min(bear[[1]]$date), max(bear[[1]]$date), length=50)
head(vv)

## estimates the UD at each time point
re <- lapply(1:length(vv), function(i) {

             ## estimate the UD. We choose a smoothing parameter of
             ## 1000 meters for X and Y coordinates, and of 72 hours
             ## for the time (after a visual exploration)
             uu <- kernelkc(bear, h = c(1000,1000,72*3600),
                            tcalc= vv[i])

             ## now, we show the result
             ## potentially, we could type
             ##
             ## jpeg(paste("UD", i, ".jpg", sep=""))
             ##
             ## to store the figures in a file, and then to build a
             ## movie with the resulting files:
             ##
             image(uu[[1]], main=vv[i])

             ## highlight the 95 percent home range
             hh <- getvolumeUDk(uu)

             contour(hh[[1]], levels=95, col="red",
                     drawlabels=FALSE, add=TRUE)

             ## and if we had typed jpeg(...) before, we have to type
             ## dev.off()
             ## to close the device. When we have finished this loop
             ## We could combine the resulting files with imagemagick
             ## (windows) or mencoder (linux)
             })


## Or, just show the home range:
re <- lapply(1:length(vv), function(i) {

             uu <- kernelkc(bear, h = c(1000,1000,72*3600),
                            tcalc= vv[i])

             pc <- getverticeshrk(uu, lev=95)
             plot(pc, xlim=c(510000, 530000),
                  ylim=c(6810000, 6825000), main=vv[i])
             })








##################################################
##
## Example with several wild boars (linear time)

## load wild boar data
data(puechcirc)


## keep only the first two circuits:
puech <- puechcirc[1:2]


## Now load te map of the elevation
data(puechabon)
elevation <- getkasc(puechabon$kasc, 1)


## compute the time point at which the UD is to be estimated
vv <- seq(min(puechcirc[[2]]$date), max(puechcirc[[2]]$date),
          length=50)


## The estimate the UD
re <- lapply(1:length(vv),
             function(i) {

                 ## We choose a smoothing parameter of 300 meters for
                 ## the x and y coordinates and of one hour for the time
                 ## (but try to play with these smoothing parameters)

                 uu <- kernelkc(puechcirc, h=c(300,300,3600),
                                tcalc = vv[i], same4all=TRUE,
                                extent=0.1)

                 ## show the elevation
                 image(elevation, main=vv[i],
                       xlim=c(698000,704000),
                       ylim=c(3156000,3160000))

                 ## and the UD, with contour lines
                 colo <- c("red","blue")
                 lapply(1:length(uu), function(i) {
                    contour(uu[[i]], col=colo[i], add=TRUE)
                 })

                 ## the blue contour lines show the UD of the mother and
                 ## the red ones correspond to her son. Adult wild boars
                 ## are known to be more "shy" that the youger ones.
                 ## Here, the low elevation corresponds to crop area
                 ## (vineyards). The young boar is the first and the
                 ## last in the crops
             })








##################################################
##
## Example with the bear, to illustrate (circular time)

data(bear)

## We consider a time cycle of 24 hours.
## the following vector contains the time points on the
## time circle at which the UD is to be estimated (note that
## the time is given in seconds)
vv <- seq(0, 24*3600-1, length=40)


## for each time point:
re <- lapply(1:length(vv),
             function(i) {

                 ## Estimation of the UD for the bear. We choose
                 ## a smoothing parameter of 1000 meters for the spatial
                 ## coordinates and a smoothing parameter equal to 0.2
                 ## for the time. We set the beginning of the time
                 ## cycle at midnight (no particular reason, just to
                 ## illustrate the function). So we pass, as t0, any
                 ## object of class POSIXct corresponding t a date at
                 ## this hour, for example the 12/25/2012 at 00H00
                 t0 <- as.POSIXct("2012-12-25 00:00")
                 uu <- kernelkc(bear, h=c(1000,1000,0.2), cycle=24*3600,
                                 tcalc=vv[i], t0=t0, circular=TRUE)

                 ## shows the results
                 ## first compute the hour for the title
                 hour <- paste(floor(vv[i]/3600), "hours",
                               floor((vv[i]%%3600)/60), "min")

                 ## compute the 95% home range
                 pc <- getverticeshrk(uu, lev=95)
                 plot(pc, xlim=c(510000, 530000),
                      ylim=c(6810000, 6825000), main=hour)

                 ## compute the 50% home range
                 pc <- getverticeshrk(uu, lev=50)
                 plot(pc, add=TRUE, colpol="blue")
                 
             })
 ## Now, each home range computed at a given time point corresponds to
 ## the area used by the animal at this time period.  We may for example
 ## try to identify the main difference in habitat composition of the
 ## home-range between different time, to identify differences in
 ## habitat use between different time of the day. We do not do it here
 ## (lack of example data)










##################################################
##
## Example of the use of the function kernelkcbase and
## related functions


## load the data
data(puechabon)
locs <- puechabon$locs

## keeps only the wild boar Chou
locs <- locs[locs$Name=="Jean",]

## compute the number of days since the beginning
## of the monitoring
dd <- cumsum(c(0, diff(strptime(locs$Date, "%y%m%d"))))
dd

## compute xyt. Note that t is here the number of
## days since the beginning of the monitoring (it
## is not an object of class POSIXt, but it may be)
xyt <- data.frame(locs[,c("X", "Y")], dd)

## Now compute the time points at which the UD is to be estimated:
vv <- 1:61

## and finally, show the UD changed with time:
re <- lapply(1:length(vv),
             function(i) {
                 ud <- kernelkcbase(xyt, h=c(300,300,20), 
                                    tcalc=vv[i], grid=100)
                 image(ud, main=vv[i])
                 contour(getvolumeUDs(ud), level=95,
                         col="red", lwd=2, add=TRUE)

                 ## Just to slow down the process
                 Sys.sleep(0.2)
                 })




## End(Not run)