The function calculates the total number of days (termed `detection days') during which individuals were detected at passive acoustic telemetry receivers. To implement the function, a dataframe with passive acoustic telemetry detections of individuals at receivers must be supplied. Detection days can be calculated for individuals/receivers in this dataframe, for specific individual/receiver pairs or all combinations of specified individuals and receivers. The function returns a dataframe of detection days for these individual/receiver combinations or a vector of detection days that is matched against another dataframe.
get_detection_days(
acoustics,
individual_id = NULL,
receiver_id = NULL,
type = c(1L, 2L),
match_to = NULL,
...
)A dataframe that contains passive acoustic telemetry detection time series (see dat_acoustics for an example). This should contain the following columns: a vector of individual IDs, named `individual_id'; a vector of receiver IDs, named `receiver_id'; and a POSIXct vector of time stamps when detections were made, named `timestamp'.
(optional) A vector of individuals for which to calculate detection days. Values not in acoustics are dropped with a warning.
(optional) A vector of receivers for which to calculate detection days. Values not in acoustics are dropped with a warning.
If both individual_id and receiver_id are specified, then type is an integer that defines whether or not to calculate detection days for (a) each individual/receiver pair (type = 1L) or (b) all combinations of individuals/receivers.
(optional) A dataframe against which to match detection days. This must contain the `individual_id' and `receiver_id' column, as in acoustics. If supplied, an integer vector of detection days for individual/receiver combinations, matched against the individuals/receivers in match_to, is returned (see also Value).
Additional arguments (depreciated).
If match_to is un-supplied, the function returns a dataframe with the detection days for individual/receiver pairs in acoustics or specific pairs/all possible pairs of specified individuals and receivers. Individual(s) and receiver(s) (if specified via individual_id and receiver_id) not in acoustics are dropped with warning(s). If match_to is supplied, a vector of detection days, matched against each individual/receiver observation in that dataframe, is returned.
To calculate detection days for all individuals in acoustics across all receivers (rather than by each receiver), simply use dplyr (see Examples).
This function does not currently support other time steps (e.g., detection hours).
#### Example (1): Detection days between all combinations
# ... of detected individuals and receivers with detections
dat <- get_detection_days(dat_acoustics)
utils::head(dat)
#> receiver_id individual_id detection_days
#> 1 3 25 5
#> 2 3 28 46
#> 3 3 35 84
#> 4 4 25 2
#> 5 7 25 1
#> 6 9 25 1
#### Example (2) Detection days between specified individual/receiver pairs
dat <- get_detection_days(dat_acoustics,
individual_id = c(25, 28),
receiver_id = c(3, 24),
type = 1L
)
utils::head(dat)
#> receiver_id individual_id detection_days
#> 1 3 25 5
#> 2 3 28 46
#> 3 24 25 12
#> 4 24 28 1
#### Example (3) Detection days between all combinations of specified
# ... individuals/receivers
dat <- get_detection_days(dat_acoustics,
individual_id = c(25, 28),
receiver_id = c(3, 24),
type = 2L
)
utils::head(dat)
#> individual_id receiver_id detection_days
#> 1 25 3 5
#> 2 28 3 46
#> 3 25 24 12
#> 4 28 24 1
#### Example (4) Match detection days to another dataframe
dat_acoustics$detection_days <- get_detection_days(dat_acoustics,
match_to = dat_acoustics,
type = 1L
)
utils::head(dat_acoustics)
#> individual_id transmitter_id index timestamp receiver_id
#> 1 25 A69-1303-555 1 2016-03-17 01:50:00 26
#> 2 25 A69-1303-555 2 2016-03-17 01:52:00 26
#> 3 25 A69-1303-555 4 2016-03-17 01:54:00 26
#> 4 25 A69-1303-555 5 2016-03-17 01:58:00 26
#> 5 25 A69-1303-555 7 2016-03-17 02:00:00 26
#> 6 25 A69-1303-555 8 2016-03-17 02:04:00 26
#> receiver receiver_long receiver_lat receiver_depth detection_days
#> 1 VR2W-108163 -5.610733 56.37628 25 16
#> 2 VR2W-108163 -5.610733 56.37628 25 16
#> 3 VR2W-108163 -5.610733 56.37628 25 16
#> 4 VR2W-108163 -5.610733 56.37628 25 16
#> 5 VR2W-108163 -5.610733 56.37628 25 16
#> 6 VR2W-108163 -5.610733 56.37628 25 16
#### Example (5): Detection days for all individuals across all individuals
# Simply use dplyr:
require(dplyr)
dat_acoustics %>%
mutate(date = as.Date(timestamp)) %>%
group_by(individual_id) %>%
summarise(detection_days = length(unique(date)))
#> # A tibble: 3 × 2
#> individual_id detection_days
#> <int> <int>
#> 1 25 256
#> 2 28 151
#> 3 35 196