pf_plot_1d.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pf_analyse_path.R
\name{pf_plot_1d}
\alias{pf_plot_1d}
\title{Plot one-dimensional depth time series from a PF 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{
\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’), timesteps (`timestep') and the depth associated with each cell along each path (`cell_z').}

\item{archival}{A dataframe of depth (m) observations named `depth', as used by \code{\link[flapper]{dc}} and \code{\link[flapper]{acdc}}.}

\item{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.}

\item{pretty_axis_args, xlab, ylab, type, ...}{Plot customisation arguments passed to \code{\link[prettyGraphics]{pretty_plot}}.}

\item{add_lines}{A named list, passed to \code{\link[graphics]{lines}}, to customise the appearance of the depth time series for reconstructed path(s).}

\item{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 (\code{prompt = TRUE}), or with all reconstructed time series on a single plot (\code{prompt = FALSE}).}
}
\value{
The function returns a plot of the observed and reconstructed depth time series, either for all paths at once (if \code{prompt = FALSE}) or each path separately (if \code{prompt = TRUE}).
}
\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.
}
\details{
Observed and reconstructed depth time series can differ due to measurement error, which is controlled via the \code{calc_depth_error} function in the DC and ACDC algorithms (see \code{\link[flapper]{dc}} and \code{\link[flapper]{acdc}}).
}
\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)
}

}
\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 the outputs 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. \code{\link[flapper]{pf_loglik}} calculates the log-probability of each path.
}
\author{
Edward Lavender
}