make_matrix_detections: Matricise detection time series

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

Matricise detection time series

Description

This function creates a list of matrices that, for each individual (list element), defines the number of detections of that individual in each time interval (matrix row) at each receiver (matrix column). To implement the function, a dataframe with acoustic detection time series must be provided via acoustics. The time intervals over which to count detections are provided by optionally defining a start and end date (these can be taken from the range of times in acoustics if unspecified) and the interval (delta_t) between time steps. By default, matrix elements that are ‘outside’ individual or receiver deployment periods are defined as 0 (not detected) but can be changed to another value (e.g., NA) via set_outside. In this case, the acoustics dataframe also needs to include the deployment times for each individual and an additional dataframe must be supplied with the same information for receivers via moorings.

Usage

make_matrix_detections(
  acoustics,
  moorings = NULL,
  start = NULL,
  end = NULL,
  delta_t = "120 mins",
  simplify = NULL,
  set_outside = NULL,
  as_POSIXct = as.POSIXct,
  set_names = TRUE,
  verbose = TRUE
)

Arguments

acoustics	A dataframe that defines passive acoustic telemetry detection time series. This should contain the following columns: a vector of individual IDs, named ‘individual_id’; a (factor) vector of receiver IDs, named ‘receiver_id’. If set_outside is specified, this should also contain POSIXct vectors of the start and end time of each individual's time at liberty, named ‘tag_start_date’ and ‘tag_end_date’ respectively.
moorings	(optional) If set_outside is specified, moorings is dataframe that defines passive acoustic telemetry receiver metadata. This should contain the following columns: a vector of receiver IDs, named 'receiver_id (as in acoustics); and POSIXct vectors of the start and end times of each receiver's deployment time, named ‘receiver_start_date’ and ‘receiver_end_date’ respectively.
start, end	POSIXct objects that define the start and end time. If unspecified, these are taken from the range of detection times in acoustics.
delta_t	A number or character that defines the time interval between successive time steps. This is passed to the ‘by’ argument of seq.POSIXt.
simplify	(optional) A function that simplifies detection matrices, such as function(x) (x > 0) + 0 to convert counts into a boolean outcomes that define whether or a detection was made.
set_outside	(optional) A value (e.g., NA) that is assigned to any matrix element that is outside of an individual's or receiver's deployment period when detection was not possible.
as_POSIXct	A function that coerces any supplied times that are not POSIXct objects to POSIXct objects.
set_names	A logical variable that defines whether or not to set the row and column names of the matrix to the time steps and the receiver IDs respectively.
verbose	A logical variable that defines whether or not to print messages to the console to relay function progress.

Value

A matrix, or a list of matrices (one for each individual in acoustics if there is more than one individual) with one column for each time step and one column for each receiver. Each cell defines whether (1) or not (0) the individual was detected (or, if set_outside is supplied, it could not have been detected) during that time step. All matrices are expressed across the same sequence of time steps and receivers.

Author(s)

Edward Lavender

Examples

#### Example (1) Construct matrix from detected individuals using detection time series
dat_acoustics$receiver_id <- factor(dat_acoustics$receiver_id)
mat_by_id <- make_matrix_detections(dat_acoustics)
summary(mat_by_id)
range(mat_by_id[[1]])

#### Example (2) Construct matrix across all receivers and use set_outside
dat_moorings$receiver_id <- factor(dat_moorings$receiver_id)
dat_acoustics$receiver_id <- factor(dat_acoustics$receiver_id,
  levels = levels(dat_moorings$receiver_id)
)
match_index <- match(dat_acoustics$individual_id, dat_ids$individual_id)
dat_acoustics$tag_start_date <- dat_ids$tag_start_date[match_index]
dat_acoustics$tag_end_date <- as.Date("2017-06-02")
mat_by_id <- make_matrix_detections(dat_acoustics,
  moorings = dat_moorings,
  set_outside = NA
)
summary(mat_by_id)

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