dcq: The 'quick' depth-contour (DCQ) algorithm

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

The ‘quick’ depth-contour (DCQ) algorithm

Description

This function implements the ‘quick’ depth-contour (DCQ) algorithm. As for the DC algorithm (dc), the DCQ algorithm relates one-dimensional depth time series to a two-dimensional bathymetry surface to determine the extent to which different parts of an area might have (or have not) been used, or effectively represent occupied depths, over time. However, a modified (binning) approach is used that is much faster and normalisation is not implementedd. To implement the function, a list of depth time series, one for each time unit (e.g. month/season) need to be supplied, along with a bathymetry raster. For each time unit, the function counts the number of depth observations in each user-defined depth bin (e.g., 10 m depth bins) and then relates these counts to the local bathymetry to produce a raster in which the value of each cell is given by the number of times in which the depth bin for that cell was used. The function returns a list of rasters, one for each time unit, and a plot of these rasters, if requested.

Usage

dcq(
  archival_ls,
  bathy,
  bin = 10,
  transform = NULL,
  plot = TRUE,
  before_plot = NULL,
  after_plot = NULL,
  fix_zlim = FALSE,
  one_page = FALSE,
  cl = NULL,
  varlist = NULL,
  verbose = TRUE,
  ...
)

Arguments

archival_ls	A list of dataframes, with one element for each time unit (e.g., month), which contain depth time series to be related to the local bathymetry. Each dataframe should contain a column of depths (‘depth’) and a column that defines the time unit (‘time_unit’). Depth should be recorded using absolute values in the same units as the bathymetry (see below).
bathy	A raster of the bathymetry in an area within which the animal is likely to have been located over the study. Bathymetry values should be recorded as absolute values and in the same units as for depths (see archival_ls).
bin	A number that defines the interval into which depth observations are binned. This should be provided in the same units as depths (see archival_ls) and the bathymetry (see bathy). The appropriate value of bin depends on the measurement error of the bathy data and the depth time series, the tidal range in an area, computational requirements, and scale of biological research objectives. For large depth time series and/or large, high-resolution bathymetry rasters, it can be useful to test the algorithm's speed using a relatively large bin.
transform	(optional) A function, such as sqrt, to transform counts. This affects the returned rasters and any plots produced (see Value). Be careful with some functions, such as log, which can generate problematic outputs (such as z axis limits if these are not defined manually), in some situations (for example, if some cells in the area are not visited).
plot	A logical input that defines whether or not to plot the rasters. If plot = TRUE, the function produces a plot for each time unit.
before_plot, after_plot	(optional) Stand-alone functions that are executed before and after the plot for each time unit is created, respectively. For example, it may be useful to plot the coast in an area before each raster is plotted, or add custom axes after each plot has been produced.
fix_zlim, one_page, ...	(optional) Plot customisation options. fix_zlim is a logical input that defines whether or not to fix z axis limits across all plots (to facilitate comparisons), or a vector of two numbers that define a custom range for the z axis which is fixed across all plots. fix_zlim = FALSE produces plots in which the z axis is allowed to vary flexibly between time units. one_page is a logical input that defines whether or not to produce all plots on one page; this is only implemented if there are fewer than 25 time units, beyond which there are typically to many plots to fit on one page. Additional plot customisation arguments can be passed to image.plot via ....
cl, varlist	(optional) Parallelisation options. cl is (a) a cluster object from makeCluster or (b) an integer that defines the number of child processes. varlist is a character vector of variables for export (see cl_export). Exported variables must be located in the global environment. If a cluster is supplied, the connection to the cluster is closed within the function (see cl_stop). For further information, see cl_lapply and flapper-tips-parallel.
verbose	A logical input that defines whether or not to relay messages to the console to monitor function progress.

Value

The function returns a named list of rasters, one for each time unit, in which the value of each cell is the number of times that that cell was represented by the corresponding depth bin in the depth time series.

Author(s)

Edward Lavender

See Also

This is a modified version of the DC algorithm implemented by dc. The ACDC algorithm (see acdc) extends the depth-contour algorithm by integrating information from acoustic detections of individuals at each time step to restrict the locations in which depth contours are identified.

Examples

#### Define data for examples
# Define archival time series with required columns ('depth' and 'time_unit')
dat_archival <- dat_archival[order(dat_archival$timestamp), ]
dat_archival$time_unit <- cut(dat_archival$timestamp, "weeks")
# Define a list of dataframes with one element for each time unit
archival_ls <- split(dat_archival, f = dat_archival$time_unit)
# Define bathymetry data (and coastline data for plotting)
bathy <- prettyGraphics::dat_gebco
coastline <- prettyGraphics::dat_coast_around_oban

#### Example (1) Implement the dcq() algorithm with 25 m bins
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 25,
  plot = FALSE
)
# The function returns a list of rasters, with one raster
# ... for each time unit.
dcq_maps

#### Example (2): Implement the algorithm in parallel:
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 25,
  plot = FALSE,
  cl = parallel::makeCluster(2L)
)

#### Example (3): Visualise the function outputs on one page
# ... using standard options.
# Examine results with 25 m bin
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 25,
  plot = TRUE,
  one_page = TRUE
)
# Examine results with a higher resolution bin
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 5,
  plot = TRUE,
  one_page = TRUE
)

#### Example (4): Plot customisation options
# fix zlim to be constant across all plots to enable comparability
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 5,
  plot = TRUE,
  one_page = TRUE,
  fix_zlim = TRUE
)
# fix zlim using custom limits across all plots
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 5,
  plot = TRUE,
  one_page = TRUE,
  fix_zlim = c(0, 5000)
)
# Transform the returned and plotted rasters by supplying a function to the
# ... transform argument
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 5,
  plot = TRUE,
  one_page = TRUE,
  transform = sqrt
)
# Customise the plot further via before_plot, after_plot functions
# ... and other arguments passed via ... E.g., note the need to include
# ... add = TRUE because the raster plot is added to the plot of the coastline.
dcq_maps <- dcq(
  archival_ls = archival_ls,
  bathy = bathy,
  bin = 5,
  plot = TRUE,
  one_page = TRUE,
  transform = sqrt,
  fix_zlim = FALSE,
  before_plot = function(x) raster::plot(coastline),
  after_plot = function(x) raster::lines(coastline),
  add = TRUE,
  col = topo.colors(100)
)

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