pf_kud.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pf_kud.R
\name{pf_kud}
\alias{pf_kud}
\title{Smooth POU maps}
\usage{
pf_kud(
  xpf,
  sample_size = NULL,
  estimate_ud = adehabitatHR::kernelUD,
  grid,
  ...,
  trial_cells = list(),
  trial_grids = list(),
  mask = NULL,
  plot = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{xpf}{A POU \code{\link[raster]{raster}} object (from \code{\link[flapper]{pf_plot_map}}).}

\item{sample_size}{(optional) An integer expansion factor for the number of locations used for KUD estimation. If supplied, \eqn{n} locations are randomly sampled from \code{xpf} with replacement in line with their probability, where \eqn{n = n_{pou} \times sample_size} and \eqn{n_{pou}} is the number of non-zero POU scores. This resampling approach avoids treating locations as `relocations'.}

\item{estimate_ud}{A function (either \code{\link[adehabitatHR]{kernelUD}} or \code{\link[flapper]{kud_around_coastline}}) that estimates the KUD.}

\item{grid, ...}{Arguments passed to \code{estimate_ud} (and ultimately \code{\link[adehabitatHR]{kernelUD}}, where they are defined) to estimate the KUD. If \code{\link[flapper]{kud_around_coastline}} is supplied to \code{estimate_ud}, then \code{grid} must be a \code{\link[sp]{SpatialPixelsDataFrame}}. The resultant KUD is resampled onto \code{xpf}.}

\item{trial_cells, trial_grids}{(Optional) Lists that define the numbers of locations (cells) and the grids used for time trials. If either \code{trial_cells} or \code{trial_grids} is supplied, the function implements \code{estimate_ud} for small (trial) numbers of cells and any grid(s) specified. If \code{trial_cells} is supplied, but not \code{trial_grids}, then \code{grid} is used for estimation. If \code{trial_grids} is supplied but not \code{trial_cells}, then time trials are implemented for each grid with 10, 50 and 100 locations. For each grid, the linear regression of the time required to estimate the KUD is plotted against the number of locations and used to predict the time required to fit the KUD to all locations. The user is then asked whether or not to continue with estimation across all locations.}

\item{mask}{(optional) A spatial mask (see \code{\link[raster]{mask}}).}

\item{plot}{A logical input that defines whether or not to plot the KUD.}

\item{verbose}{A logical input that defines whether or not to print messages to the console to monitor function progress.}
}
\value{
The function (a) plots the outcomes of time trials (if requested), (b) estimates and plots a KUD (if requested) and (c) returns a \code{\link[raster]{raster}} of the KUD.
}
\description{
This function smooths proportion-of-use (POU) maps (from \code{\link[flapper]{pf_plot_map}}) by applying kernel utilisation distribution (KUD) estimation. Depending on the implementation, following optional initial time trials, using a subset, all or an expanded sample of POU locations, the function applies a KUD smoother via a user-supplied estimation routine (i.e., \code{\link[adehabitatHR]{kernelUD}} or \code{\link[flapper]{kud_around_coastline}}). The function extracts the KUD as a \code{\link[raster]{raster}}, applies a spatial mask (e.g., coastline), plots the processed KUD (if specified) and returns this as a \code{\link[raster]{raster}}.
}
\details{
For computational efficiency, it may be necessary to aggregate (and renormalise) POU scores across the \code{grid} used for estimation before implementing this function.
}
\examples{
#### Define POU map for examples
out_dcpf_s <- pf_simplify(dat_dcpf_histories,
  summarise_pr = TRUE,
  return = "archive"
)
out_dcpf_pou <- pf_plot_map(out_dcpf_s, dat_dcpf_histories$args$bathy)

#### Example (1): Implement function using default options
pf_kud(xpf = out_dcpf_pou, grid = 10)

#### Example (2): Implement function using resampling
pf_kud(xpf = out_dcpf_pou, sample_size = 100, grid = 10)

#### Example (3): Implement time trials
if (interactive()) {
  # Implement time trials for specified numbers of cells
  pf_kud(
    xpf = out_dcpf_pou,
    sample_size = 100,
    grid = 60,
    trial_cells = list(10, 100, 1000, 10000)
  )
  # Implement time trials for specified grids
  pf_kud(
    xpf = out_dcpf_pou,
    sample_size = 100,
    grid = 180,
    trial_grids = list(60, 120, 180)
  )
  # Implement time trials for specified numbers of cells and grids
  pf_kud(
    xpf = out_dcpf_pou,
    sample_size = 100,
    grid = 10,
    trial_cells = list(10, 100, 1000, 10000),
    trial_grids = list(10, 30, 60)
  )
}

#### Example (4): Force alignment between POU scores and grids for speed
# Example with numeric grid
out_dcpf_pou_agg <-
  raster::aggregate(out_dcpf_pou, fact = 2)
out_dcpf_pou_agg <-
  out_dcpf_pou_agg / raster::cellStats(out_dcpf_pou_agg, "sum")
grid <- raster::res(out_dcpf_pou_agg)[1]
pf_kud(out_dcpf_pou_agg, grid = grid)
# Example with SpatialPixels grid
grid <- kud_habitat(out_dcpf_pou_agg)
pf_kud(out_dcpf_pou_agg, grid = grid)

}
\author{
Edward Lavender
}