pf_plot_3d.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pf_analyse_path.R
\name{pf_plot_3d}
\alias{pf_plot_3d}
\title{Map three-dimensional paths from a PF algorithm}
\usage{
pf_plot_3d(
  paths,
  bathy,
  add_paths = list(line = list(width = 10)),
  shift = 5,
  stretch = -5,
  aspectmode = "data",
  prompt = FALSE,
  ...
)
}
\arguments{
\item{paths}{A dataframe containing reconstructed movement path(s) from \code{\link[flapper]{pf}} via \code{\link[flapper]{pf_simplify}} (see \code{\link[flapper]{pf_path-class}}). At a minimum, this should contain a unique identifier for each path (named `path_id') and the x, y and z coordinates that define the trajectory of each path (`cell_x', `cell_y' and `cell_z').}

\item{bathy}{A \code{\link[raster]{raster}} of the bathymetry surface over which movement was reconstructed.}

\item{add_paths}{A named list, passed to \code{\link[plotly]{add_paths}}, to customise the appearance of the paths.}

\item{shift}{A number that vertically shifts the paths above the surface (\code{bathy}). The default is \code{shift = 5}, which shifts paths 5 m above the surface. This helps to ensure that paths are visible on interactive, three-dimensional \code{\link[plotly]{plotly}} plots.}

\item{stretch}{A number that vertically stretches the height of the surface (see \code{\link[prettyGraphics]{pretty_scape_3d}}). The default is \code{-5} which negates the bathymetry and stretches it five-fold.}

\item{aspectmode}{A character that defines the shape of the plot: \code{"cube"} produces a cube; \code{"data"} produces a plot whether the size of the x, y and z axes is scaled according to the data (see \code{\link[prettyGraphics]{pretty_scape_3d}}).}

\item{prompt}{A logical input that defines whether or not plot each path on a separate plot, sequentially, with a pause between plots (\code{prompt = TRUE}), or all paths on a single plot (\code{prompt = FALSE}).}

\item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_scape_3d}}, for plot customisation.}
}
\value{
The function maps the trajectories of reconstructed paths across the bathymetry surface in three-dimensions, returning a single map if \code{prompt = FALSE} or one map for each path if \code{prompt = TRUE}. The function also invisibly returns the plot object, if \code{prompt = TRUE}, or a list of plot objects, if \code{prompt = FALSE} (with one element for each path), to facilitate further modification.
}
\description{
This function is a simple wrapper for \code{\link[prettyGraphics]{pretty_scape_3d}} that maps the paths reconstructed by the depth-contour or acoustic-container depth-contour particle filtering algorithms (DCPF and ACDCPF) over a surface in three dimensions.
}
\details{
This function requires the \code{\link[plotly]{plotly}} package.
}
\examples{
#### Implement pf() algorithm
# Here, we use pre-defined outputs for speed
# Note that it may be beneficial to interpolate paths between points
# ... e.g., via lcp_interp() prior to plotting, but we will not do that here.
bathy <- dat_dcpf_histories$args$bathy
paths <- dat_dcpf_paths

#### Example (1): Visualise paths using the default options
pf_plot_3d(paths, bathy)

#### Example (2): Customise the plot
# Customise via add_paths() list
pf_plot_3d(paths, bathy,
  add_paths = list(
    line = list(color = "black", width = 10),
    marker = list(color = "blue", size = 10)
  )
)
# Adjust shift, stretch or aspectmode
pf_plot_3d(paths, bathy, shift = 200, stretch = -10)
# Customise via ... e.g., add coastline:
coast <- raster::crop(dat_coast, bathy)
pf_plot_3d(paths, bathy, coastline = coast)
# The returned plot objects can also be used for further customisation.

#### Example (3): Plot individual paths separately
if (interactive()) {
  pf_plot_3d(paths, bathy, prompt = TRUE)
}

}
\seealso{
\code{\link[flapper]{pf}} implements the pf algorithm. \code{\link[flapper]{pf_plot_history}} visualises particle histories, \code{\link[flapper]{pf_plot_map}} creates an overall `probability of use' map from particle histories and \code{\link[flapper]{pf_simplify}} processes these into a dataframe of movement paths. \code{\link[flapper]{pf_plot_1d}}, \code{\link[flapper]{pf_plot_2d}} and \code{\link[flapper]{pf_plot_3d}} provide plotting routines for paths. For mapping, it can be useful to interpolate shortest (least-cost) paths between sequential locations via \code{\link[flapper]{lcp_interp}}. \code{\link[flapper]{pf_loglik}} calculates the log-probability of each path.
}
\author{
Edward Lavender
}