Identify `resident' individuals in a passive acoustic telemetry array

Source: R/get_detections.R

This function identifies `resident' individuals in a passive acoustic telemetry array from acoustic detection time series.

get_residents(
  acoustics,
  fct = NULL,
  resident_threshold_gap = 31,
  resident_threshold_duration = c(91.2501, 365.25),
  resident_labels = c("S", "L"),
  non_resident_label = "N",
  keep = NULL
)

Arguments

acoustics

A dataframe that contains passive acoustic telemetry detection time series (see dat_acoustics for an example). At a minimum, this should contain a POSIXct vector of time stamps when detections were made named `timestamp'.

fct

(optional) A character that defines the name of a column in acoustics that distinguishes acoustic time series for different individuals.

resident_threshold_gap

A number that specifies the maximum gap (days) between detections for an individual to be considered `resident' over the period of detections.

resident_threshold_duration

A sorted, numeric vector that specifies the duration (days) over which `regular' detections (spaced less than resident_threshold_gap apart) must occur for an individual to be considered as `resident'. A vector can be supplied to distinguish multiple residency categories (e.g., short-term residents and long-term residents).

resident_labels

A character vector of labels, one for each resident_threshold_duration, for residency categories (e.g., short-term and long-term residents).

non_resident_label

A character that defines the label given to non-residents.

keep

A character vector of column names in acoustics to retain in the returned dataframe (e.g., `sex', `maturity' etc.).

Value

The function returns a dataframe that defines, for each individual (fct), the duration (days) between the first detection and the last detection in a series of detections spaced less than resident_threshold_gap days apart (`time'), and the residency category (as defined by resident_threshold_duration and resident_labels).

Details

This function assigns residency categories (e.g., non-resident, short-term resident, long-term resident) to individuals in acoustics, returning a dataframe with one row for each individual and a column for assigned residency categories. `Resident' individuals are defined as individuals with (a) `regular' detections (i.e. detections spaced less than some threshold time (resident_threshold_duration) apart) that (b) last for a requisite time interval (resident_threshold_duration). Multiple residency categories can be specified. Under the default options, non-residents are labelled "N". Short-term residents (labelled "S") are defined as individuals for which sequential detections were less than 31 days apart for more than 91 days (three months). Long-term residents (labelled "L") are defined as individuals for which sequential detections were less than 31 days apart for more than 365 days (12 months).

A method argument may be added in due course to implement other methods to define `resident' individuals (e.g., based on detection days, see get_detection_days) .

References

Lavender, et al. (in 2021). Movement patterns of a Critically Endangered elasmobranch (Dipturus intermedius) in a Marine Protected Area. Aquatic Conservation: Marine and Freshwater Ecosystems, 32(2), 348--365. https://doi.org/10.1002/aqc.3753

Author

Edward Lavender

Examples

#### Example (1): Implement default options
get_residents(dat_acoustics, fct = "individual_id")
#>   individual_id     time resident
#> 1            25 441.1722        L
#> 2            28 220.4486        S
#> 3            35 397.2486        L
# Compare results to abacus plot
prettyGraphics::pretty_plot(dat_acoustics$timestamp, dat_acoustics$individual_id)