define_recapture: Identify and describe recapture events from depth time series...

In edwardlavender/Tools4ETS: Tools for Ecological Time Series

Identify and describe recapture events from depth time series on known dates

Description

Identifying 'recapture' events in depth time series (i.e. moments when electronically tagged animals are (re)caught, brought to the surface and possibly released again) is often useful. This function uses a (semi-)automatic approach to define the precise time of recapture on a set of pre-known dates when the individual was recaptured; note that this assumes the individual was only caught once on any given date. (Identifying recapture events without pre-defined windows in which these are known to have occurred is challenging, but suggest_recapture implements one approach.) The function can use three methods to define likely times of recapture on inputted dates. Under the automatic approach, the time of recapture identified by the first method is taken as correct and saved, along with all of the positions in a user-defined window around this recapture time that encapsulate the recapture event. The user can inspect a plot of depth ~ time to visually assess the performance of these algorithms. Under the semi-automated approach, the user can use point-and-click on the plot to re-define the time of recapture, which is often difficult to define exactly without manual input (although the algorithm will usually come close), and/or other time stamps during the recapture process which are biologically important. The function returns a list which includes the estimated times of recapture events and, depending on user inputs, may include a processed dataframe from which all positions around estimated recapture positions have been removed.

Usage

define_recapture(
  data_depth,
  data_recapture,
  method = 1:3,
  bin = "10 mins",
  bound_am = 60 * 60 * 8,
  bound_pm = 60 * 60 * 17,
  define_time_before = function(recapture_time) {
     recapture_time - 2 * 60 * 60
 },
  define_time_after = function(recapture_time) {
     as.POSIXct(as.Date(recapture_time)
    + 1, tz = "UTC")
 },
  inspect_plot = TRUE,
  before4plot = 3600,
  after4plot = 3600,
  ylim = c(-250, 0),
  vcols = c("black", "green", "blue"),
  type = "b",
  cex = 0.5,
  pch = 21,
  col = "black",
  bg = "black",
  prompt = TRUE,
  manual_flag = TRUE,
  select = 1,
  remove_recaptures = FALSE,
  ...
)

Arguments

data_depth	A dataframe in which recapture events need to be identified based on depth or temperature time series. This must contain the following named columns: a unique identifier for each individual ('id'); time stamps in POSIXct format ('timestamp'); depth ('depth'); and (optionally) temperature ('temp'). Note that depth must be a positive number.
data_recapture	A dataframe which specifies the dates on which recapture events are known to have occurred, but for which the precise timing needs to be resolved. This must contain the following named columns: a unique identifier for each individual ('id'), that matches IDs in data_depth, and the date ('Date').
method	A numeric vector that defines the method(s) used to define the timing of recapture events: 1, identifies the time of minimum depth (i.e. the shallowest moment); 2, identifies the time preceding the highest average decrease in depth (i.e., movement shallower); and 3 specifies the time of maximum temperature. See Details for further information.
bin	A string that defines the duration of the bin over which the mean change in depth is calculated. This is required if method 2 is included. The default is "10 mins".
bound_am	A numeric value that defines the number of seconds after midnight on any given day before which a 'recapture event' is implausible. The default is 28800 (i.e., any recapture event identified before 08:00 hours on a given day will be flagged with a warning indicating the identified time of recapture is unlikely).
bound_pm	A numeric value, as above, which defines the number of seconds on any given day after which a 'recapture event' is considered implausible. The default is 61299 (i.e., any recapture event identified after 17:00 hours on a given day will be flagged with a warning).
define_time_before	A function which takes a single argument (the recapture time, in POSIXct format) and outputs a time (in POSIXct format) which defines the lower bound of a recapture window. The default is a function which returns a time 2 hours before a given recapture window.
define_time_after	A function, as above, which defines the upper bound of a recapture window. The default is a function which returns midnight on the day of recapture.
inspect_plot	A logical input which defines whether or not to create a plot of depth (negated) ~ time stamp, with the recapture window and the identified time(s) of recapture highlighted. This is useful for visualising the performance of the default options for defining the time of recapture.
before4plot	A numeric input defining the number of seconds before the recapture time, estimated using the first method inputted, which is used to define the lower x limit of the plot. The default is 3600 (i.e. the time series plot will begin from one hour before the estimated recapture time).
after4plot	A numeric input, as above, used to define the upper x limit of the plot. The default is 3600 (i.e. the time series plot will extend until one hour after the estimated recapture time).
ylim	A numeric vector of two which specifies the y limits of the plot. Note that depth is negated for plotting purposes (see inspect_plot), so ylim needs to be negated too. The default is ylim = c(-250, 0).
vcols	A vector of colours. The recapture time estimated by each method is added to the time series plot as a vertical line, with the specified colour.
type, pch, col, bg, cex, ...	Additional graphical customisation options passed to pretty_plot, excluding xlim, pretty_axis_args and main which are handled internally.
prompt	A logical input which defines whether or not to pause following the creation of a plot (see above). If prompt = TRUE, the function proceeds once the user has digested the plot and pressed Enter. Otherwise, the user can press Esc to end the algorithm.
manual_flag	A logical input which defines whether or not to manually flag points on the plot. This is useful because the function's estimate of the recapture time may not be exactly correct and may need to be refined by the user, and because the user may want to define flag points in the recapture window which represent the times of biologically important events. If TRUE, the function pauses whilst the user clicks points on the plot to be saved.
select	A numeric value which, if manual_flag = TRUE, specifies the position of the click which defines the exact time of recapture. (This is useful if the user uses multiple clicks to define important points in the recapture window, only one of which represents the 'moment' of recapture.)
remove_recaptures	A logical input defining whether or not to remove identified recaptures (either based on the first input method or, if manual_flag = TRUE, the time defined by the click number given by the select argument). If TRUE, the function will also return a vector of all the positions in recapture windows and a reduced dataframe (data_depth_rem_recap) in which these have been removed.

Details

Three methods can be used to define the time of recapture on pre-specified dates. The first method identifies the time when depth is shallowest. This method is effective if (a) depth data are accurate in shallow water and (b) individuals spent a relatively short amount of time at the surface. However, if depth data are inaccurate in shallow water, then the time when depth is shallowest may not actually reflect the moment of recapture. Moreover, if individuals spend a long time at/near the surface, the identified moment of recapture using this method may be too late. The second method identifies the time when the change in depth is greatest. To do this, the function calculates the change in depth between sequential observations and then the average change in each user-specified bin (e.g. 10 mins). This method can be more effective than the first window in cases where individuals are rapidly brought to the surface. The third method identifies the time of maximum temperature. This method can be effective in situations in which temperature data are more accurate than depth data and spikes in temperature are expected with movement from deeper water into shallower water/air. Note that this is not necessarily always the case; some environments lack strong thermoclines and there may be times and/or areas in which an individual could rise through the water column and/or into air and experience a decline, increase or no change in temperature. Hence, implementing all three methods is often beneficial. Each method will usually identify a similar time window, but the exact time of recapture can be adjusted by the user. Otherwise, the time identified by the first method is used (e.g. to define all the observations within the user-specified recapture window).

Value

A list with the following elements: (1) 'recapture_event_details' (a list); (2) 'recapture_times' (a dataframe); and, if the user has selected to remove recaptures, (3) 'recapture_rows' (a numeric vector) and (4) 'data_depth_rem_recap' (a dataframe). (1) 'recapture_event_details' is a list which contains an element for each recapture event. Each element is itself a list which contains: (a) 'data_recapture_event', the data row from data_recaptures which describes the ID/time stamp of the event in question; (b) 'rc_time_ls', a list defining the estimated time of recapture by each method; (c) 'rc_time', a list containing the chosen estimated time of recapture, the method used (1, 2, 3 or manual) and, if the manual method is used, the click number which was used to define the time of recapture); (d) 'reasonable_bounds', a list containing the time window within which recapture events are considered plausible and outside of which a warning is flagged; (e) 'recapture rows', a numeric vector which defines all the positions in data_depth within the user-defined recapture window around the chosen estimated time of recapture for the individual in question. If no data is associated with a recapture event, a warning is given and other elements are NA/NULL. (2) 'recapture_times' is a dataframe which, for each row in 'data_recapture' (i.e., individual and date of recapture) specifies the time stamp of each recapture event and the method used (i.e., this is a synthesis of the information provided by each element in 'recapture_event_details'). (3) 'recapture_rows_all' is a numeric vector which specifies all the positions in data_depth which lie within recapture windows. (4) 'data_depth_rem_recap' is the data_depth dataframe with these positions removed.

Author(s)

Edward Lavender

Examples

#### Method
# We will precisely identify recapture events in the two example flapper skate time series,
# ... based on knowledge of the following recapture dates:
# Individual A was recaught on "2016-05-16"
# Individual B was recaught on "2016-05-10"

#### Pre-processing
# dat_flapper has all required columns except date:
dat_flapper$date <- as.Date(dat_flapper$timestamp)
# define dates of recapture for data_recapture argument:
dat_recap <- data.frame(id = c("A", "B"), date = as.Date(c("2016-05-16", "2016-05-10")))

#### Example (1): Define recaptures for two individuals on known dates
define_recap <-
  define_recapture(
    # Supply depth time series and recapture dataframes
    data_depth = dat_flapper,
    data_recapture = dat_recap,
    # Implement method 1:3
    method = 1:3,
    # bin is required for method 2
    bin = "10 mins",
    # Define reasonable boundaries
    bound_am = 3600*8,
    bound_pm = 3600*17,
    # We'll consider a recapture window between 1 hour before and after the estimated time
    define_time_before = function(recapture_time) { recapture_time - 3600 },
    define_time_after = function(recapture_time) { recapture_time + 3600 },
    # We'll examine the plot with default graphical parameters:
    inspect_plot = TRUE,
    before4plot = 3600,
    after4plot = 3600,
    vcols = c("black", "green", "blue"),
    # prompt = TRUE and manual_flag are advisable, but we'll turn them off here
    # ... for the purposes of illustration
    prompt = FALSE,
    manual_flag = FALSE,
    # Select is ignored because manual_flag = FALSE but we'll remove recapture
    # ... windows around the estimated recapture time
    select = 1,
    remove_recaptures = TRUE
    )
# The function returns multiple outputs
summary(define_recap)
# We have a list of recapture details for each recapture event
utils::str(define_recap$recapture_event_details)
# We have a dataframe defining the precise times of recapture
utils::str(define_recap$recapture_times)
# We have all the positions in the raw data (data_depth) with lie within recapture windows
utils::str(define_recap$recapture_rows_all)
# We also opted to return a reduced dataframe without those positions:
utils::str(define_recap$data_depth_rem_recap)

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