get_detection_area_ts.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_area_ts}
\alias{get_detection_area_ts}
\title{Calculate the area sampled by receivers 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{
\item{xy, detection_range, coastline, scale}{Arguments required to calculate the total area surveyed by receivers (at each time point) via \code{\link[flapper]{get_detection_area_sum}}. For this function, \code{xy} should be a \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that includes both receiver locations and corresponding deployment times (in columns named `receiver_start_date' and `receiver_end_date' respectively).}

\item{plot}{A logical input that defines whether or not to plot a time series of the total area sampled by receivers.}

\item{verbose}{A logical input that defines whether or not to print messages to the console to relay function progress.}

\item{cl, varlist}{(optional) Parallelisation options. \code{cl} is (a) a cluster object from \code{\link[parallel]{makeCluster}} or (b) an integer that defines the number of child processes. \code{varlist} is a character vector of variables for export (see \code{\link[flapper]{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 \code{\link[flapper]{cl_stop}}). For further information, see \code{\link[flapper]{cl_lapply}} and \code{\link[flapper]{flapper-tips-parallel}}.}

\item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{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 \code{plot = TRUE}, the function also returns a plot of the area sampled by receivers through time.
}
\description{
This function extends \code{\link[flapper]{get_detection_area_sum}} to calculate how the total area sampled by receivers changes through time.
}
\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"
  )

}
\author{
Edward Lavender
}