pf_plot_3d: Map three-dimensional paths from a PF algorithm

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Map three-dimensional paths from a PF algorithm

Description

This function is a simple wrapper for 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.

Usage

pf_plot_3d(
  paths,
  bathy,
  add_paths = list(line = list(width = 10)),
  shift = 5,
  stretch = -5,
  aspectmode = "data",
  prompt = FALSE,
  ...
)

Arguments

paths	A dataframe containing reconstructed movement path(s) from pf via pf_simplify (see 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’).
bathy	A raster of the bathymetry surface over which movement was reconstructed.
add_paths	A named list, passed to add_paths, to customise the appearance of the paths.
shift	A number that vertically shifts the paths above the surface (bathy). The default is shift = 5, which shifts paths 5 m above the surface. This helps to ensure that paths are visible on interactive, three-dimensional plotly plots.
stretch	A number that vertically stretches the height of the surface (see pretty_scape_3d). The default is -5 which negates the bathymetry and stretches it five-fold.
aspectmode	A character that defines the shape of the plot: "cube" produces a cube; "data" produces a plot whether the size of the x, y and z axes is scaled according to the data (see pretty_scape_3d).
prompt	A logical input that defines whether or not plot each path on a separate plot, sequentially, with a pause between plots (prompt = TRUE), or all paths on a single plot (prompt = FALSE).
...	Additional arguments, passed to pretty_scape_3d, for plot customisation.

Details

This function requires the plotly package.

Value

The function maps the trajectories of reconstructed paths across the bathymetry surface in three-dimensions, returning a single map if prompt = FALSE or one map for each path if prompt = TRUE. The function also invisibly returns the plot object, if prompt = TRUE, or a list of plot objects, if prompt = FALSE (with one element for each path), to facilitate further modification.

Author(s)

Edward Lavender

See Also

pf implements the pf algorithm. pf_plot_history visualises particle histories, pf_plot_map creates an overall ‘probability of use’ map from particle histories and pf_simplify processes these into a dataframe of movement paths. pf_plot_1d, pf_plot_2d and pf_plot_3d provide plotting routines for paths. For mapping, it can be useful to interpolate shortest (least-cost) paths between sequential locations via lcp_interp. pf_loglik calculates the log-probability of each path.

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)
}

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.