suggest_recapture: Explore putative, unrecorded recapture events within depth...

In edwardlavender/Tools4ETS: Tools for Ecological Time Series

Explore putative, unrecorded recapture events within depth time series

Description

For animals tagged with archival tags, this function highlights putative, unrecorded recapture events (when tagged individuals may have been captured by recreational anglers). To do this, the function bins each individual's time series into a series of time windows. In each window, the function identifies all of the time steps when the individual's depth was shallower than a specified threshold: these are ‘putative capture events’. Windows that contain putative capture event(s) are termed capture windows. For each capture window, the depth time series can be inspected visually to clarify whether or not movement into shallow water is likely to reflect capture (e.g., if putative capture events occurred at a reasonable time of day and the shape of changes in depth are consistent with that expected to be caused by capture). The function returns a list, with one element for each capture window, that contains the depth time series within that window.

Usage

suggest_recapture(
  data,
  fct = NULL,
  threshold = 1,
  window = 60 * 60 * 12,
  plot = TRUE,
  pretty_axis_args = list(side = 3:2),
  buffer = 60 * 60,
  add_threshold_markers = list(col = "blue", lty = 3),
  add_additional = NULL,
  prompt = TRUE,
  prompt_warning = 100,
  ...
)

Arguments

data	A dataframe of depth time series. This must contain a POSIXct vector of time stamps (‘timestamp’) and a numeric vector of absolute depths (‘depth’). A column can be included to distinguish levels of a grouping factor (e.g., individuals) (see fct).
fct	(optional) A character that defines the name of a column in data that distinguishes levels of a grouping factor (e.g., individuals).
threshold	A number that defines the depth threshold; depth(s) shallower than threshold are flagged as putative capture event(s).
window	A number that defines the duration (s) of capture windows.
plot	A logical input that defines whether or not to plot, for each capture window, depth (which is internally negated for plotting) against time, with putative capture events flagged.
pretty_axis_args	If plot = TRUE, pretty_axis_args is named list, passed to pretty_axis, to control plot axes.
buffer	A number, or a vector of two numbers, used to adjust the time (s) of the first and last putative capture events in each capture window to define x axis limits. For example, buffer = c(60, 90) minuses 60 s from the time of the first capture event in a window and adds 90 s to the time of the last capture event in the window and these times are taken to define the x limits of the plot.
add_threshold_markers	(optional) If plot = TRUE, add_threshold_markers is a named list, passed to lines, used to flag the time steps when the depth was shallower than the threshold on the plot using vertical lines. add_threshold_markers = list() implements default graphical options. add_threshold_markers = NULL suppresses this option.
add_additional	(optional) If plot = TRUE, add_additional is function used to add additional elements to each plot. This must accept two arguments, even if they are ignored: an index (the capture window number) and the data within the capture window that is plotted.
prompt	If plot = TRUE, prompt is a logical input that defines whether or not to pause function execution between sequential plots.
prompt_warning	If plot = TRUE and prompt = TRUE, prompt_warning is a number that defines the number of capture windows with putative capture events above which the function will warn the user to reconsider prompt = TRUE.
...	Additional arguments passed to pretty_plot, excluding xlim, which is controlled via window and buffer.

Details

This function was motivated by the need to identify putative, unrecorded recreational angling events for tagged flapper skate (Dipturus intermedius) during individuals' time at liberty. The skate are typically targeted by recreational anglers over areas of deep (> 100 m) water, so angling events are visible as dramatic spikes in the depth time series caused by ascent into shallow water.

For each individual's time series, the function groups observations into a series of windows and identifies all of the time steps within each window when the depth was shallower than the threshold. For each capture window (a window that contains putative capture event(s)), a dataframe of the depth time series/putative capture events within that window is returned. If plot = TRUE, for each window, a plot of the depth time series also returned with all moments when the depth was shallower than the threshold flagged for visible inspection. Putative capture events can then be evaluated according to the time of day when they occurred, the shape of the depth time series or other relevant factors.

Value

The function returns a list, with one element for each capture window, that contains the depth time series within that window. If plot = TRUE, for each window, a plot of the depth time series also returned.

Author(s)

Edward Lavender

See Also

define_recapture defines the precise time of known capture events.

Examples

#### Example (1): Implement function with default options
# One potential capture event identified
events <- suggest_recapture(data = dat_flapper, fct = "id", prompt = FALSE)
utils::str(events)

#### Example (2): Adjust capture threshold
events <- suggest_recapture(data = dat_flapper,
                            fct = "id",
                            threshold = 10,
                            prompt = FALSE)

#### Example (3) Adjust capture window size
# Adjust capture window
events <- suggest_recapture(data = dat_flapper,
                            fct = "id",
                            threshold = 20,
                            window = 60*60*24*7,
                            prompt = FALSE)
# Adjust plot x limits via buffer
events <- suggest_recapture(data = dat_flapper,
                            fct = "id",
                            threshold = 20,
                            window = 60*60*24*7,
                            buffer = 60*60*24*2,
                            prompt = FALSE)

#### Example (4): Customise plot

## Adjust vertical flags via add_threshold_markers
events <- suggest_recapture(data = dat_flapper,
                            add_threshold_markers = list(col = "red"),
                            fct = "id",
                            prompt = FALSE)

## Use add_additional e.g, to provide useful plot titles
# Define a function, which must depend on an index and the data, to add plot titles
# These will depend on the capture window index and
# ... we will add a * to flag putative events that occurred during the day
# ... (which are more likely to reflect actual capture events).
add_main <- function(index, data){
  # Define title
  title <- paste0("[", index, "]")
  # Identify events during the day and add this to title
  day <- data[data$depth <= 5, ]
  if(nrow(day) > 0){
    day$hour <- hour_dbl(day$timestamp)
    day <- day[day$hour >= 8 & day$hour <= 20, ]
  }
  if(nrow(day) > 0){
    title <- paste0(title, "*")
  }
  # Add plot title to plot
  mtext(side = 3, text = title, line = 1.25, font = 2)
}
# Implement function
events <- suggest_recapture(data = dat_flapper,
                            threshold = 10,
                            fct = "id",
                            add_additional = add_main,
                            prompt = FALSE)

## Pass additional arguments via ...
events <- suggest_recapture(data = dat_flapper,
                            fct = "id",
                            prompt = FALSE,
                            type = "l")

edwardlavender/Tools4ETS documentation built on Nov. 29, 2022, 7:41 a.m.