make_df_detections: Convert a detection matrix into a dataframe

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

Convert a detection matrix into a dataframe

Description

This function converts a matrix of detections (0, 1) by time stamp and receiver into a dataframe.

Usage

make_df_detections(
  acoustics,
  only_keep_detections = FALSE,
  set_names = FALSE,
  as_POSIXct = as.POSIXct
)

Arguments

acoustics	A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. ‘Meaningful’ time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see set_names).
only_keep_detections	A logical variable that defines whether or not to retain only observations that correspond to detections. (If only_keep_detections = FALSE, the returned dataframe includes time stamps without detections.)
set_names	A logical variable that defines whether or not to take the row and column names of acoustics as the time stamps and receiver IDs. (If set_names = FALSE, time stamps and receiver IDs are simply given as integer vectors of 1 to the number of rows or columns respectively.)
as_POSIXct	If set_names = TRUE, as_POSIXct is a function that converts the row names of acoustics into POSIXct time stamps.

Value

The function returns a dataframe with time stamps (‘timestamp’) and receivers (‘receiver_id’). If set_names = FALSE, these are integer vectors that match the dimensions of acoustics. Otherwise they are are taken from row and column names of acoustics. In this case, if as_POSIXct is defined, time stamps are returned in POSIXct format and receivers are returned as a factor. If only_keep_detections = FALSE, the dataframe also includes a ‘detection’ column that defines whether (1) or not (0) a detection was made for each observation; otherwise, this column is dropped (mirroring real-world data).

Author(s)

Edward Lavender

Examples

#### Define detection matrix
# Simulate array
array <- sim_array(
  boundaries = raster::extent(-1000, 1000, -1000, 1000),
  n_receivers = 24, seed = 1
)
# Simulate movement in this area
path <- sim_path_sa(n = 50, area = array$array$area, seed = 1)
# Simulate a detection matrix
detections <- sim_detections(
  n = 100,
  path = path$xy_mat,
  xy = sp::coordinates(array$array$xy),
  calc_detection_pr = function(dist) ifelse(dist < 425, 1, 0),
)
# Extract matrix
mat <- detections$det_mat
# Define row names
rownames(mat) <-
  as.character(
    seq(as.POSIXct("2016-01-01"), by = "2 mins", length.out = nrow(mat))
  )

#### Examples: convert the matrix to a dataframe
utils::str(mat)
dat <- make_df_detections(mat)
utils::str(dat)
dat <- make_df_detections(mat, only_keep_detections = TRUE)
utils::str(dat)
dat <- make_df_detections(mat, only_keep_detections = TRUE, set_names = TRUE)
utils::str(dat)

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