pf_plot_1d: Plot one-dimensional depth time series from a PF algorithm

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

Plot one-dimensional depth time series from a PF algorithm

Description

This function plots the observed depth time series and the depth time series associated with each path reconstructed by the depth-contour particle filtering (DCPF) or acoustic-container depth-contour particle filtering (ACDCPF) algorithm.

Usage

pf_plot_1d(
  paths,
  archival,
  scale = -1,
  pretty_axis_args = list(side = 3:2),
  xlab = "Time (index)",
  ylab = "Depth (m)",
  type = "b",
  add_lines = list(col = "royalblue", type = "b"),
  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’), timesteps ('timestep’) and the depth associated with each cell along each path (‘cell_z’).
archival	A dataframe of depth (m) observations named ‘depth’, as used by dc and acdc.
scale	A number that vertically scales the depth time series for the observations and the reconstructed path(s). By default, absolute values for depth are assumed and negated for ease of visualisation.
pretty_axis_args, xlab, ylab, type, ...	Plot customisation arguments passed to pretty_plot.
add_lines	A named list, passed to lines, to customise the appearance of the depth time series for reconstructed path(s).
prompt	A logical input that defines whether or not plot the observed depth time series with each reconstructed depth time series on a separate plot, sequentially, with a pause between plots (prompt = TRUE), or with all reconstructed time series on a single plot (prompt = FALSE).

Details

Observed and reconstructed depth time series can differ due to measurement error, which is controlled via the calc_depth_error function in the DC and ACDC algorithms (see dc and acdc).

Value

The function returns a plot of the observed and reconstructed depth time series, either for all paths at once (if prompt = FALSE) or each path separately (if prompt = TRUE).

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 the outputs into a dataframe of movement paths. pf_plot_1d, pf_plot_2d and pf_plot_3d provide plotting routines for paths. pf_loglik calculates the log-probability of each path.

Examples

#### Implement pf() algorithm
# Here, we use pre-defined outputs for speed
paths <- dat_dcpf_paths
archival <- dat_dc$args$archival

#### Example (1): The default implementation
pf_plot_1d(paths, archival)

#### Example (2): Plot customisation options, e.g.:
pf_plot_1d(paths, archival, scale = 1, pretty_axis_args = list(side = 1:2))
pf_plot_1d(paths, archival, type = "l")
pf_plot_1d(paths, archival, add_lines = list(col = "red", lwd = 0.5))

#### Example (3): Plot individual comparisons
if (interactive()) {
  pp <- graphics::par(mfrow = c(3, 4))
  pf_plot_1d(paths, depth, prompt = TRUE)
  graphics::par(pp)
}

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