get_residents: Identify 'resident' individuals in a passive acoustic...

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

Identify ‘resident’ individuals in a passive acoustic telemetry array

Description

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

Usage

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

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

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

Author(s)

Edward Lavender

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

See Also

get_detection_days, get_detection_clumps

Examples

#### Example (1): Implement default options
get_residents(dat_acoustics, fct = "individual_id")
# Compare results to abacus plot
prettyGraphics::pretty_plot(dat_acoustics$timestamp, dat_acoustics$individual_id)

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