lcp_interp.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lcps.R
\name{lcp_interp}
\alias{lcp_interp}
\title{Interpolate shortest (least-cost) paths between locations along a movement path}
\usage{
lcp_interp(
  paths,
  surface,
  ...,
  keep_cols = FALSE,
  calc_distance = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{paths}{A dataframe that defines movement paths. This must contain a unique, integer identifier for each path from 1 to the number of paths (`path_id'); an integer time step index (`timestep') and the coordinates of sequential locations (`cell_x' and `cell_y'). The example dataset comprising movement paths reconstructed over the seabed by the depth-contour particle filtering algorithm (\code{\link[flapper]{dat_dcpf_paths}}) exemplifies of the appropriate format.}

\item{surface}{A \code{\link[raster]{raster}} of the surface over which the object (i.e., individual) moved between sequential locations. \code{\link[flapper]{lcp_over_surface}} forces some restrictions on the form of this raster. The \code{surface} must be planar (i.e., Universal Transverse Mercator projection) with units of metres and equal resolution in the x, y and z directions (see \code{\link[flapper]{lcp_over_surface}}).}

\item{...}{Additional arguments, passed to \code{\link[flapper]{lcp_over_surface}}, to control the interpolation (excluding \code{origin}, \code{destination}, \code{combination} and \code{goal}).}

\item{keep_cols}{A logical input that defines whether or not to retain all columns in \code{paths} in the returned dataframe (see Value).}

\item{calc_distance}{A logical input that defines whether or not to calculate distances between sequential positions along the shortest paths (see Value).}

\item{verbose}{A logical input that defines whether or not to print messages to the console to monitor function progress.}
}
\value{
The function returns a dataframe or a list depending on the input to \code{calc_distance}. If \code{calc_distance = FALSE}, the function returns a dataframe that defines, for each path (`path_id'), for each time step (`timestep'), a vector of the cell coordinates (`cell_x', `cell_y', `cell_z') on the \code{surface} that define the shortest path from the location at the previous time step to the location at the current time step. Thus, the first row contains the individual's initial location and subsequent rows for that time step (\code{timestep = 2} if the first time step is defined as \code{timestep =  1}, since movement is considered from the location at the `previous' time step to the location at the `current' time step) include the sequential locations of an individual, were it to have moved along the shortest path, to the location at the next time step.  If \code{keep_cols = TRUE}, coordinate columns are suffixed by `.x' and the coordinates for each time step (as inputted) are included (with the `.y' suffix) along with any other columns in the inputted dataframe (\code{paths}).

If \code{calc_distance = TRUE}, a named list is returned with two elements. The `path_lcp' element contains the dataframe of interpolated path coordinates, as described above, with an extra `dist' column that defines the distance over the surface between sequential positions along the path. The `dist_lcp' element contains a dataframe, exactly as inputted via \code{paths}, but with the total distance along each shortest path (from the `previous' location to the `current' location) included as a `dist' column (this is simply the sum of the distances provided in \code{path_lcp$dist}) for all movements within each timestep for each path.
}
\description{
This function is a wrapper for \code{\link[flapper]{lcp_over_surface}} designed to interpolate shortest (least-cost) paths between sequential locations along an animal movement path. The function is specifically motivated for the interpolation of paths between locations for benthic animals, whose movement is restricted by the seabed (see \code{\link[flapper]{lcp_over_surface}}).
}
\details{
If \code{calc_distances = TRUE}, distances are calculated with movement from the previous location to the `current' location (see Value).

A useful application of this function in \code{\link[flapper]{flapper}} is the post-hoc evaluation of particle filtering movement algorithms (see \code{\link[flapper]{pf}}). These can be implemented using movement models based on Euclidean or shortest distances. Since the former is typically much faster, a useful starting point is to implement the chosen algorithm using Euclidean distances and then, for the sample of paths reconstructed by the algorithm, use \code{\link[flapper]{lcp_interp}} to examine the similarity between Euclidean and shortest distances and the effects of updated distance values on movement probabilities. If a Euclidean distances implementation of an algorithm is acceptable (i.e., minimum swimming distances are not too large under the movement model), shortest distances from \code{\link[flapper]{lcp_interp}} can be used to adjust the movement probabilities to more realistic values. Alternatively, a shortest distances implementation of the movement path algorithm may be necessary.

This function can also be useful for visualising movement paths (e.g., via \code{\link[flapper]{pf_plot_3d}}).
}
\examples{
#### Define movement paths
# We will interpolate LCPs between sequential locations
# ... of a skate on the seabed
# ... reconstructed by the DCPF algorithm (dc() & pf()), using the
# ... example dat_dcpf_* datasets. We extract the paths
# ... and the surface over which movement occurred from this object:
paths <- dat_dcpf_paths
surface <- dat_dcpf_histories$args$bathy

#### Example (1): Implement lcp_interp() for an example path
# ... with calc_distance = FALSE
# Implement approach
paths_1 <- paths[paths$path_id == 1, ]
paths_interp_1 <- lcp_interp(
  paths = paths_1,
  surface = surface,
  calc_distance = FALSE
)
# With calc_distance = FALSE, we get a dataframe with sequential locations
utils::head(paths_interp_1)

#### Example (2): Keep the original columns in 'paths'
# ... via keep_cols = TRUE
paths_interp_2 <- lcp_interp(
  paths = paths_1,
  surface = surface,
  calc_distance = FALSE,
  keep_cols = TRUE
)
utils::head(paths_interp_2)

#### Example (3): Calculate shortest distances along each path
# ... via calc_distance = TRUE (the default)
paths_interp_3 <- lcp_interp(
  paths = paths_1,
  surface = surface
)
# A named list is returned
names(paths_interp_3)
# The 'dist_lcp' element is as inputted but with a 'dist' column that defines
# ... the total distance along the shortest path between sequential locations
utils::head(paths_interp_3$dist_lcp)
# The 'path_lcp' element contains the paths, as described above, with an
# ... additional 'dist' column for the distances between sequential locations
# ... along each shortest path (i.e., time step)
utils::head(paths_interp_3$path_lcp)

}
\author{
Edward Lavender
}