-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathget_detection_overlaps.Rd
101 lines (94 loc) · 7.37 KB
/
get_detection_overlaps.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_overlaps}
\alias{get_detection_overlaps}
\title{Get `overlapping' detections}
\usage{
get_detection_overlaps(acoustics, overlaps = NULL, clock_drift = 5)
}
\arguments{
\item{acoustics}{A dataframe of passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example) for a single individual. This must contain an integer vector of receiver IDs, named `receiver_id' and a POSIXct vector of time stamps when detections were made, named `timestamp'.}
\item{overlaps}{(optional) A named list, from \code{\link[flapper]{get_detection_containers_overlap}}, that defines, for each receiver, for each day over its deployment period, whether or not its detection container overlapped with those of other receivers.}
\item{clock_drift}{A number that defines the time (s) between sequential detections at which they are considered to have occurred at `effectively the same time'.}
}
\value{
The function returns a message that defines the number of detections at different receivers that occurred at effectively the same time (within \code{clock_drift}) and, if \code{overlaps} is supplied, the subset of these that occurred at non-overlapping receivers. A dataframe is also invisibly returned that records the details of overlapping detections. This includes the following columns:
\itemize{
\item \code{timestamp_1}, a POSIXct vector of time stamps at which detections were made;
\item \code{receiver_id_1}, an integer identifier of the receivers at which detections were made;
\item \code{timestamp_2}, a POSIXct vector of the time stamps at which immediately subsequent detections were made;
\item \code{receiver_id_2}, an integer identifier of the receivers at which the immediately subsequent detections were made;
\item \code{diff_time}, a numeric vector that defines the time (s) between consecutive detections (\code{timestamp_1} and \code{timestamp_2});
\item \code{detection_in_overlapping_container}, a binary vector that defines whether (1) or not (0) the detection containers of \code{receiver_id_1} and \code{receiver_id_2} overlapped at the time of the detection (this is only included if \code{overlaps} is provided);
}
}
\description{
This function isolates detections that occurred at `effectively the same time' at different receivers with overlapping or non-overlapping detection containers. To implement the function, a dataframe of acoustic detections for a specific individual (\code{acoustics}) is required. Within this dataframe, the function isolates any detections that occurred within a user-specified time interval (\code{clock_drift}) at different receivers. If a list of the receivers with overlapping detection containers in space and time is supplied (\code{overlaps}), the function also flags the subset of these detections that occurred at receivers with overlapping or non-overlapping detection containers. This information is important for identifying potential false detections and the implementation of the AC* algorithm(s) (see Details). The function returns this information via summary message(s) along with a dataframe of the overlapping detections.
}
\details{
Detections at different receivers that occur at effectively the same time have important implications for inferences of animal movement patterns, especially via the AC* algorithm(s) in \code{\link[flapper]{flapper}} (e.g. \code{\link[flapper]{acdc}}). Within the AC* algorithm(s), when an individual is detected at the same time at two different receivers, detection probability kernels dictate that these receivers must have overlapping detection containers. If the detection containers do not overlap, this suggests that either (a) receiver clocks are not well-aligned; (b) the definition of `effectively the same time' is be overly large (such that the individual could move from within the detection container of one receiver into the detection container of another); (c) detection containers are too small and detection probability is higher than realised; and/or (d) one or more of the detections are false. The most likely cause may be guided by knowledge of the array design, detection probability and false detection algorithms. For example, if it is plausible that detection containers are too small, repeating the implementation of this function with larger containers may indicate whether or not this is likely to have been the case: if so, all detections that occurred at effectively the same time at receivers with non-overlapping detection containers should be captured by the large containers (though this does not rule out other explanations). The purpose of this function is to flag any such detections so that they can be investigated and addressed prior to the implementation of the AC* algorithm(s).
}
\examples{
#### Example (1): Implement function using detection data for an example individual
dat_acoustics_25 <- dat_acoustics[dat_acoustics$individual_id == 25, ]
dat <- get_detection_overlaps(acoustics = dat_acoustics_25)
utils::head(dat)
#### Example (2): Implement function, including information on detection containers
## Get detection container overlaps to include in function
## (see ?flapper::get_detection_container_overlaps)
# Define receiver locations
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
containers <- get_detection_containers(xy, byid = TRUE)
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)
# Define detection container overlaps
overlaps <- get_detection_containers_overlap(containers = containers)
## Implement function with detection container overlaps included
dat <- get_detection_overlaps(acoustics = dat_acoustics_25, overlaps = overlaps)
utils::head(dat)
#### Implement function across all individuals
# For some individuals, there are simultaneous detections at receivers with
# ... non overlapping detection containers, suggesting these are probably too small.
dat_by_id <-
lapply(
split(dat_acoustics, dat_acoustics$individual_id),
function(acc_for_id) {
print(paste("individual_id", acc_for_id$individual_id[1], "-------"))
get_detection_overlaps(acoustics = acc_for_id, overlaps = overlaps)
}
)
## Test this hypothesis by re-implementing approach with larger containers
# Re-define containers and receiver overlap
containers <- get_detection_containers(xy, detection_range = 750, byid = TRUE)
containers <- sp::SpatialPolygonsDataFrame(containers, containers_df)
overlaps <- get_detection_containers_overlap(containers = containers)
# Re-implement algorithm
dat_by_id <-
lapply(
split(dat_acoustics, dat_acoustics$individual_id),
function(acc_for_id) {
print(paste("individual_id", acc_for_id$individual_id[1], "-------"))
get_detection_overlaps(acoustics = acc_for_id, overlaps = overlaps)
}
)
# There are now no observations within clock_drift at receivers with
# ... non-overlapping containers.
}
\author{
Edward Lavender
}