get_detection_containers.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_containers}
\alias{get_detection_containers}
\title{Define detection containers around receivers}
\usage{
get_detection_containers(
  xy,
  detection_range = 425,
  resolution = 1000,
  boundaries = NULL,
  coastline = NULL,
  plot = TRUE,
  ...
)
}
\arguments{
\item{xy}{A \code{\link[sp]{SpatialPoints-class}} or \code{\link[sp]{SpatialPointsDataFrame-class}} object that defines receiver locations. The coordinate reference system should be the Universe Transverse Mercator coordinate reference system.}

\item{detection_range}{A number that defines the detection range (m) of receivers.}

\item{resolution}{A number that defines the number of linear segments used to approximate the detection container (see the \code{quadsegs} argument in \code{\link[rgeos]{gBuffer}}).}

\item{boundaries}{An \code{\link[raster]{extent}} object (on an object from which this can be extracted) that defines the boundaries of the study area.}

\item{coastline}{(optional) A \code{\link[sp]{SpatialPolygonsDataFrame-class}} object that defines barriers (such as the coastline) that block receivers from surveying areas within their detection range.}

\item{plot}{A logical input that defines whether or not to plot receivers, their containers, and the buffer (if specified).}

\item{...}{Additional arguments passed to \code{\link[rgeos]{gBuffer}}, such as \code{byid}.}
}
\value{
The function returns a \code{\link[sp]{SpatialPolygons-class}} object of the detection containers around receivers that represents the area they survey under the assumption of a constant detection range, accounting for any barriers to detection. By default, this will contain a single feature, which is suitable for the calculation of the total area surveyed by receivers (see \code{\link[flapper]{get_detection_area_sum}}) because it accounts for the overlap in the detection ranges of receivers. However, if \code{byid = TRUE} is passed via \code{...} to \code{\link[rgeos]{gBuffer}}, the returned object will have a feature for each pair of coordinates in \code{xy} (i.e., receiver). This is less appropriate for calculating the area surveyed by receivers, since areas surveyed by multiple receivers will be over-counted, but it is suitable when the containers for particular receivers are required (e.g., to extract environmental conditions within a specific receiver's detection range) (see \code{\link[flapper]{get_detection_containers_envir}}).
}
\description{
This function defines the areas surveyed by receivers (termed `detection containers') as a spatial object, based on an estimate of the detection range (m) and any barriers to detection. To implement the function, receiver locations must be supplied as a SpatialPoints or SpatialPointsDataFrame object with the Universe Transverse Mercator coordinate reference system. The function defines a spatial buffer around each receiver according to the estimated detection range, cuts out any barriers to detection, such as the coastline, and returns a SpatialPolygons object that defines the combined detection container across all receivers or receiver-specific detection containers.
}
\examples{
#### Define receiver locations as a SpatialPoints object with a UTM CRS
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@data <- as.data.frame(xy)

#### Example (1): Get the simplest containers around receivers
get_detection_containers(xy)

#### Example (2): Account for barriers in the study area
get_detection_containers(xy, coastline = dat_coast)

#### Example (3): Adjust the detection range
get_detection_containers(xy, detection_range = 400, coastline = dat_coast)
get_detection_containers(xy, detection_range = 500, coastline = dat_coast)

#### Example (4): Suppress the plot
get_detection_containers(xy, coastline = dat_coast, plot = FALSE)

#### Example (5): Output characteristics are controlled via byid
# A SpatialPolygons object with one feature is the implicit output
sp_1 <- get_detection_containers(xy, coastline = dat_coast, byid = FALSE)
sp_1
# A SpatialPolygons object with one feature for each element in xy
# ... can be returned via byid = TRUE
sp_2 <- get_detection_containers(xy, coastline = dat_coast, byid = TRUE)
sp_2
# The total area of the former will be smaller, since areas covered
# ... by multiple receivers are merged
rgeos::gArea(sp_1)
rgeos::gArea(sp_2)
# But it can be more convenient to use the latter format in some cases
# ... because it is easy to isolate specific containers:
raster::plot(dat_coast)
raster::plot(sp_1[1], add = TRUE, col = "red") # single feature
raster::plot(sp_2[1], add = TRUE, col = "blue") # isolate specific features

}
\author{
Edward Lavender
}