get_detection_days: Calculate detection days

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Calculate detection days

Description

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.

Usage

get_detection_days(
  acoustics,
  individual_id = NULL,
  receiver_id = NULL,
  type = c(1L, 2L),
  match_to = NULL,
  ...
)

Arguments

acoustics	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’.
individual_id	(optional) A vector of individuals for which to calculate detection days. Values not in acoustics are dropped with a warning.
receiver_id	(optional) A vector of receivers for which to calculate detection days. Values not in acoustics are dropped with a warning.
type	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.
match_to	(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).

Details

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).

Value

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.

Author(s)

Edward Lavender

See Also

get_detection_clumps, get_residents

Examples

#### Example (1): Detection days between all combinations
# ... of detected individuals and receivers with detections
dat <- get_detection_days(dat_acoustics)
utils::head(dat)

#### 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)

#### 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)

#### 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)

#### 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)))

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.