get_detection_area_ts: Calculate the area sampled by receivers through time

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

Calculate the area sampled by receivers through time

Description

This function extends get_detection_area_sum to calculate how the total area sampled by receivers changes through time.

Usage

get_detection_area_ts(
  xy,
  detection_range = 425,
  coastline = NULL,
  scale = 1/(1000^2),
  plot = TRUE,
  verbose = TRUE,
  cl = NULL,
  varlist = NULL,
  ...
)

Arguments

xy, detection_range, coastline, scale	Arguments required to calculate the total area surveyed by receivers (at each time point) via get_detection_area_sum. For this function, xy should be a SpatialPolygonsDataFrame-class object that includes both receiver locations and corresponding deployment times (in columns named ‘receiver_start_date’ and ‘receiver_end_date’ respectively).
plot	A logical input that defines whether or not to plot a time series of the total area sampled by receivers.
verbose	A logical input that defines whether or not to print messages to the console to relay function progress.
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.
...	Additional arguments, passed to pretty_plot, to customise the plot produced.

Value

The function returns a dataframe with, for each date (‘date’) from the time of the first receiver's deployment to the time of the last receiver's retrieval, the number of receivers operational on that date (‘n’) and the total area sampled (‘receiver_area’). If plot = TRUE, the function also returns a plot of the area sampled by receivers through time.

Author(s)

Edward Lavender

Examples

#### Define SpatialPointsDataFrame with receiver locations and deployment dates
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
xy <- sp::SpatialPoints(
  dat_moorings[, c("receiver_long", "receiver_lat")],
  proj_wgs84
)
xy <- sp::spTransform(xy, proj_utm)
xy <- sp::SpatialPointsDataFrame(xy, data = dat_moorings)

#### Example (1): Implement function with default arguments
dat <- get_detection_area_ts(xy)

#### Example (2): Adjust detection range, include coastline and use parallel processing
# For areas with complex coastline, this will reduce the speed of the algorithm
# So we will also supply a cluster to improve the computation time.
if (flapper_run_parallel) {
  dat <- get_detection_area_ts(xy,
    detection_range = 500,
    coastline = dat_coast,
    cl = parallel::makeCluster(2L),
    varlist = "dat_coast"
  )
}

#### Example (3) Hide or customise the plot
dat <- get_detection_area_ts(xy, plot = FALSE)
dat <-
  get_detection_area_ts(xy,
    pretty_axis_args =
      list(
        axis = list(
          list(format = "%b-%y"),
          list()
        )
      ),
    xlab = "Time (month-year)",
    ylab = expression(paste("Area (", m^2, ")")),
    type = "l"
  )

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