get_residents.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_residents}
\alias{get_residents}
\title{Identify `resident' individuals in a passive acoustic telemetry array}
\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{
\item{acoustics}{A dataframe that contains passive acoustic telemetry detection time series (see \code{\link[flapper]{dat_acoustics}} for an example). At a minimum, this should contain a POSIXct vector of time stamps when detections were made named `timestamp'.}

\item{fct}{(optional) A character that defines the name of a column in \code{acoustics} that distinguishes acoustic time series for different individuals.}

\item{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.}

\item{resident_threshold_duration}{A sorted, numeric vector that specifies the duration (days) over which `regular' detections (spaced less than \code{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).}

\item{resident_labels}{A character vector of labels, one for each \code{resident_threshold_duration}, for residency categories (e.g., short-term and long-term residents).}

\item{non_resident_label}{A character that defines the label given to non-residents.}

\item{keep}{A character vector of column names in \code{acoustics} to retain in the returned dataframe (e.g., `sex', `maturity' etc.).}
}
\value{
The function returns a dataframe that defines, for each individual (\code{fct}), the duration (days) between the first detection and the last detection in a series of detections spaced less than \code{resident_threshold_gap} days apart (`time'), and the residency category (as defined by \code{resident_threshold_duration} and \code{resident_labels}).
}
\description{
This function identifies `resident' individuals in a passive acoustic telemetry array from acoustic detection time series.
}
\details{
This function assigns residency categories (e.g., non-resident, short-term resident, long-term resident) to individuals in \code{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 (\code{resident_threshold_duration}) apart) that (b) last for a requisite time interval (\code{resident_threshold_duration}). Multiple residency categories can be specified. Under the default options, non-residents are labelled \code{"N"}. Short-term residents (labelled \code{"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 \code{"L"}) are defined as individuals for which sequential detections were less than 31 days apart for more than 365 days (12 months).

A \code{method} argument may be added in due course to implement other methods to define `resident' individuals (e.g., based on detection days, see \code{\link[flapper]{get_detection_days}}) .
}
\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)

}
\references{
Lavender, et al. (in 2021). Movement patterns of a Critically Endangered elasmobranch (\emph{Dipturus intermedius}) in a Marine Protected Area. Aquatic Conservation: Marine and Freshwater Ecosystems, 32(2), 348--365. https://doi.org/10.1002/aqc.3753
}
\seealso{
\code{\link[flapper]{get_detection_days}}, \code{\link[flapper]{get_detection_clumps}}
}
\author{
Edward Lavender
}