kud_around_coastline.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kud_tools.R
\name{kud_around_coastline}
\alias{kud_around_coastline}
\alias{kud_around_coastline_fast}
\title{Process a kernel utilisation distribution around a barrier}
\source{
This forum is a useful resource: http://r-sig-geo.2731867.n2.nabble.com/Walruses-and-adehabitatHR-class-estUDm-exclusion-of-non-habitat-pixels-and-summary-over-all-animals-td6497315.html.
}
\usage{
kud_around_coastline(xy, grid, ...)

kud_around_coastline_fast(xy, grid, ...)
}
\arguments{
\item{xy}{A \code{\link[sp]{SpatialPointsDataFrame}} object that defines the movement path(s). This should contain a column that defines the individual ID(s) as a factor.  \code{\link[flapper]{kud_around_coastline_fast}} can only handle one individual.}

\item{grid}{A \code{\link[sp]{SpatialPixelsDataFrame}} object that defines the grid over which estimation is implemented and binary habitat suitability (0, unsuitable; or 1, suitable).}

\item{...}{Additional arguments passed to \code{\link[adehabitatHR]{kernelUD}}.}
}
\value{
\itemize{
  \item \code{\link[flapper]{kud_around_coastline}} returns an object of class `estUDm'. This is a list, with one component per animal, of \code{\link[adehabitatHR]{estUD-class}} objects. The `h' slot of the output (\code{output@h}) has been modified so that the method (`meth') is given as `specified'.
  \item \code{\link[flapper]{kud_around_coastline_fast}} returns an object of class `RasterLayer'.
}
}
\description{
Given an animal movement path over a gridded surface, \code{\link[flapper]{kud_around_coastline}} estimates a `raw' kernel utilisation distribution (from \code{\link[adehabitatHR]{kernelUD}}) and then processes the distribution to account for barriers to movement, such as coastline. \code{\link[flapper]{kud_around_coastline_fast}} is a bare-bones implementation of this function for iterative applications. To implement these functions, the movement path(s) should be supplied as a SpatialPointsDataFrame and the grid over which estimation is implemented as a SpatialPixelsDataFrame with values 0 and 1 defining unsuitable and suitable habitat respectively.
}
\details{
Utilisation distributions (UDs) are bivariate probability distributions that describe the probability (density) of locating an individual in any given area at a randomly chosen time. These can be estimated using the \code{\link[adehabitatHR]{kernelUD}} function. The algorithms implemented by \code{\link[adehabitatHR]{kernelUD}} function can incorporate simple barriers, but restrictions on the shapes of barriers mean that in many real-world settings (e.g., in areas with complex coastline) barriers cannot be implemented. As a result, a pragmatic (if somewhat unsatisfactory) approach is to post-process the raw utilisation distribution by removing areas in which movement is impossible and then re-normalise the distribution (so that probabilities sum to one). These functions achieve this by implementing the estimation over a grid, which defines whether (1) or not (0) an area is `habitat'. After the estimation of the raw UD across the grid, probability density scores are combined (multiplied) with the habitat suitability score (0, 1) and then renormalised (by dividing by the total score across suitable areas).

To implement these routines, \code{\link[flapper]{kud_around_coastline}} is typically the preferable option. \code{\link[flapper]{kud_around_coastline}} is a bare-bones implementation of the routines within \code{\link[flapper]{kud_around_coastline}} that has is designed to be (marginally) faster (e.g., for iterative applications). This function skips checks on user inputs, assuming that \code{xy} and \code{grid} have been correctly specified (as a \code{\link[sp]{SpatialPointsDataFrame}} for a specific individual and a \code{\link[sp]{SpatialPixelsDataFrame}} respectively), implements the estimation and returns a \code{\link[raster]{raster}} rather than an `estUDm' object (see Value).
}
\examples{
#### Set up
## (1) Simulate path for which to compute UD
# Focus on a sample of the marine environment off Oban, West Scotland
sea <- invert_poly(dat_coast)
sea <- raster::crop(sea, update_extent(raster::extent(sea), x_shift = -2500))
prettyGraphics::pretty_map(add_polys = list(x = sea, col = "skyblue"))
# Simulate path
n <- 1000
path_ls <- sim_path_sa(
  n = n,
  area = sea,
  sim_step = function(...) stats::rgamma(1, shape = 20, scale = 20),
  seed = 1,
  plot = FALSE
)
prettyGraphics::add_sp_path(path_ls$xy_mat,
  col = viridis::viridis(n),
  length = 0.02
)
## (2) Define path as a SpatialPointsDataFrame (SpatialPoints is not allowed)
path <- sp::SpatialPointsDataFrame(
  path_ls$xy_mat,
  data = data.frame(ID = factor(rep(1, nrow(path_ls$xy_mat)))),
  proj4string = raster::crs(dat_coast)
)
## (3) Define grid over which to implement estimation
# ... The grid needs to be sufficiently small to capture the coastline
# ... reasonably while being large enough to enable calculation
# ... of the home range.
r <- raster::raster(raster::extent(dat_coast), nrows = 100, ncols = 100)
raster::values(r) <- 0
r <- raster::mask(r, dat_coast, updatevalue = 1)
habitat <- methods::as(r, "SpatialPixelsDataFrame")
sp::plot(habitat)

#### Example (1) Implement estimation and processing
## Estimate raw UD
ud_raw <- adehabitatHR::kernelUD(xy = path, grid = habitat)
# Object is of class estUDm, which is a list of estUD objects
# The outputs for each animal can be accessed by indexing
ud_raw[[1]]
# Check smoothing parameters
ud_raw[[1]]@h
## Estimate raw UD and post-process
ud_pro <- kud_around_coastline(xy = path, grid = habitat)
# The same type of object is returned
ud_pro[[1]]
# Smoothing parameters have been modified
ud_pro[[1]]@h
## Compare plots
# ... Notice that the processed version doesn't 'bleed' onto land
# ... and the scale differs due to the re-normalisation
ud_raw_r <- raster::raster(ud_raw[[1]])
ud_pro_r <- raster::raster(ud_pro[[1]])
pp <- graphics::par(mfrow = c(1, 2))
prettyGraphics::pretty_map(
  add_rasters = list(x = ud_raw_r),
  add_polys = list(x = dat_coast),
  add_paths = list(
    x = path,
    col = viridis::viridis(n),
    lwd = 0.25,
    length = 0.02
  )
)
prettyGraphics::pretty_map(
  add_rasters = list(x = ud_pro_r),
  add_polys = list(x = dat_coast),
  add_paths = list(
    x = path,
    col = viridis::viridis(n),
    lwd = 0.25,
    length = 0.02
  )
)
graphics::par(pp)

#### Further analysis can be implemented as usual
# For example we can compute the home range contours from the UD
# ... using adehabitatHR::getvolumeUD(). In practice, this converts from the
# ... probability density scale to a more intuitive \% home range scale.
# Get volume
vol_raw <- adehabitatHR::getvolumeUD(ud_raw, standardize = TRUE)
vol_pro <- adehabitatHR::getvolumeUD(ud_pro, standardize = TRUE)
# Get contours
ver_raw <- adehabitatHR::getverticeshr(ud_raw[[1]], standardize = TRUE)
ver_pro <- adehabitatHR::getverticeshr(ud_pro[[1]], standardize = TRUE)
# Rasterise
vol_raw_r <- raster::raster(vol_raw[[1]])
vol_pro_r <- raster::raster(vol_pro[[1]])
# For neatness on the plot, it is convenient to exclude areas beyond 95 \%
vol_raw_r[vol_raw_r[] > 95] <- NA
vol_pro_r[vol_pro_r[] > 95] <- NA
# Plot
pp <- graphics::par(mfrow = c(1, 2))
prettyGraphics::pretty_map(
  add_rasters = list(x = vol_raw_r),
  add_polys = list(
    list(x = dat_coast),
    list(
      x = ver_raw,
      border = "blue",
      lwd = 2
    )
  ),
  add_paths = list(
    x = path,
    col = viridis::viridis(n),
    lwd = 0.25,
    length = 0.02
  )
)
prettyGraphics::pretty_map(
  add_rasters = list(x = vol_pro_r),
  add_polys = list(
    list(x = dat_coast),
    list(
      x = ver_pro,
      border = "blue",
      lwd = 2
    )
  ),
  add_paths = list(
    x = path,
    col = viridis::viridis(n),
    lwd = 0.25,
    length = 0.02
  )
)
graphics::par(pp)

}
\author{
Edward Lavender
}