get_detection_containers_overlap.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_containers_overlap}
\alias{get_detection_containers_overlap}
\title{Get detection container overlaps}
\usage{
get_detection_containers_overlap(containers, services = NULL)
}
\arguments{
\item{containers}{A \code{\link[sp]{SpatialPolygonsDataFrame}} that defines detection containers (see \code{\link[flapper]{get_detection_containers}}). The \code{data} slot must include a dataframe with the following columns: an unique, integer identifier for each receiver (`receiver_id') and receiver deployment \code{\link[base]{Dates}} (`receiver_start_date' and `receiver_end_date').}

\item{services}{(optional) A dataframe that defines receiver IDs and servicing \code{\link[base]{Dates}} (times during the deployment period of a receiver when it was not active due to servicing). If provided, this must contain the following columns: an integer identifier for serviced receivers (named ‘receiver_id’) and two columns that define the time of the service(s) (‘service_start_date’ and ‘service_end_date’) (see \code{\link[flapper]{make_matrix_receivers}}).}
}
\value{
The function returns a list with two elements:
\itemize{
  \item \strong{overlap_by_receiver} is list, with one element for all integers from \code{1:max(containers$receiver_id)}. Any elements that do not correspond to receivers contain a NULL element. List elements that correspond to receivers contain a dataframe that defines, for each day over the deployment period (defined in `timestamp') of that receiver (defined in `receiver_id'), whether (1) or not (0) that receiver overlapped in space with every other receiver (defined in the remaining columns by their receiver IDs).
  \item \strong{overlap_by_date} is a named list, with one element for each date from the start until the end of the study (\code{min(containers$receiver_start_date):max(containers$receiver_end_date)}), that records an integer vector of all receivers with overlapping containers on that date. In this vector, each receiver overlaps with at least one other receiver (but not every receiver will necessarily overlap with every other receiver).
}
}
\description{
This functions identifies receivers with overlapping detection containers in space and time.
}
\details{
This function requires the \code{\link[tidyr]{tidyr-package}} (specifically \code{\link[tidyr]{pivot_longer}}).
}
\examples{
#### Define receiver containers
## 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")
rownames(dat_moorings) <- dat_moorings$receiver_id
xy <- sp::SpatialPoints(
  dat_moorings[, c("receiver_long", "receiver_lat")],
  proj_wgs84
)
xy <- sp::spTransform(xy, proj_utm)
xy@data <- as.data.frame(xy)
rownames(xy@data) <- dat_moorings$receiver_id
## Get receiver-specific detection containers
# ... via get_detection_containers with byid = TRUE
containers <- get_detection_containers(xy, byid = TRUE)
## Link detection containers with receiver IDs and deployment dates
# ... in a SpatialPointsDataFrame, as required for this function.
containers_df <- dat_moorings[, c(
  "receiver_id",
  "receiver_start_date",
  "receiver_end_date"
)]
row.names(containers_df) <- dat_moorings$receiver_id
containers <- sp::SpatialPolygonsDataFrame(containers, containers_df)

## Simulate some receiver 'servicing' dates for demonstration purposes
set.seed(1)
# Loop over each receiver...
services_by_receiver <- lapply(split(dat_moorings, 1:nrow(dat_moorings)), function(din) {
  # For the receiver, simulate the number of servicing events
  n <- sample(0:3, 1)
  dout <- NULL
  if (n > 0) {
    # simulate the timing of servicing events
    dates <- sample(seq(min(din$receiver_start_date), max(din$receiver_end_date), "days"), n)
    dout <- data.frame(
      receiver_id = rep(din$receiver_id, length(dates)),
      service_start_date = dates,
      service_end_date = dates
    )
  }
  return(dout)
})
services <- do.call(rbind, services_by_receiver)
rownames(services) <- NULL
if (nrow(services) == 0) services <- NULL

#### Example (1): Implement function using containers alone
overlaps_1 <- get_detection_containers_overlap(containers = containers)
summary(overlaps_1)

#### Example (2): Account for servicing dates
overlaps_2 <- get_detection_containers_overlap(
  containers = containers,
  services = services
)
# Examine the first few simulated servicing events
services[1:3, ]
# Show that the list_by_date element for the first servicing event
# ... includes the first receiver in services$receiver_id
# ... for overlaps_1 but not overlaps_2,
# ... which accounts for that fact that the receiver was serviced then:
overlaps_1$list_by_date[[as.character(services$service_start_date[1])]]
overlaps_2$list_by_date[[as.character(services$service_start_date[1])]]
# Likewise, show that the list_by_receiver element for that receiver
# ... includes overlapping receivers in overlaps_1 but not overlaps_2:
r_id <- services$receiver_id[1]
overlaps_1$list_by_receiver[[r_id]][overlaps_1$list_by_receiver[[r_id]]$timestamp \%in\%
  services$service_start_date[services$receiver_id == r_id], ]
overlaps_2$list_by_receiver[[r_id]][overlaps_2$list_by_receiver[[r_id]]$timestamp \%in\%
  services$service_start_date[services$receiver_id == r_id], ]

}
\seealso{
\code{\link[flapper]{get_detection_containers}} creates detection containers.
}
\author{
Edward Lavender
}