Suggest dBBMM / dBGB sliding-window parameters from track sampling

Inspects a move2 object's temporal sampling and proposes a window_size and margin pair for mt_dbbmm_variance or mt_dbgb_variance whose one-window temporal coverage matches a user-specified target. Diagnostic only – the function does not call the variance estimator, just prints the suggestion (and optionally plots the time-lag distribution).

Usage

mt_suggest_dbbmm_window(x, target_hours = 4, plot = TRUE)

Arguments

x: A move2 object. Single- or multi-track. The CRS does not matter – only time lags are used.
target_hours: Numeric. Target temporal coverage of one sliding window in hours. Default 4. The literature default of window_size = 31, margin = 11 corresponds to ~4 h on half-hourly tracks and ~30 min on minute-spaced tracks.
plot: Logical. If TRUE (default), plot the time-lag distribution and overlay the suggested window's temporal span.

Value

Invisibly, a list with components

window_size: Suggested integer window size.
margin: Suggested integer margin.
median_dt_secs: Median time lag in seconds.
target_hours: Target coverage used.
window_hours: Actual coverage of the suggested window in hours (window_size * median_dt_secs / 3600).
n: Number of locations.
n_windows: Approximate number of non-overlapping windows that fit in the track.

For multi-track input the list is named per individual.

Details

The dBBMM / dBGB variance estimator slides a window of window_size fixes along the track and tests within each window whether a single Brownian-motion variance or two variances (split at a breakpoint) better fit the data, requiring at least margin fixes on each side of any tested breakpoint (Kranstauber et al. 2012). The temporal coverage of one window is window_size * median(dt) for typical tracks.

This helper picks window_size as the nearest odd integer to target_hours * 3600 / median(dt), clamped to a minimum of 11 (the smallest window that gives reasonable BIC stability) and to at most floor(n/4) so several non-overlapping windows fit along the track. margin is set to the nearest odd integer to (window_size - 1) / 4, satisfying the window_size >= 2 * margin + 1 constraint with comfortable headroom.

Heuristics aside, the right window_size depends on the biology of the species and the question being asked. Sweep a few values around the suggestion when the result matters.

References

Kranstauber, B., Kays, R., LaPoint, S. D., Wikelski, M., & Safi, K. (2012). A dynamic Brownian bridge movement model to estimate utilization distributions for heterogeneous animal movement. Journal of Animal Ecology, 81(4), 738-746. doi:10.1111/j.1365-2656.2012.01955.x

Examples

if (FALSE) { # \dontrun{
library(move2)
fishers <- mt_read(mt_example())
s <- mt_suggest_dbbmm_window(fishers, target_hours = 4)
s
## use the suggestion:
var_obj <- mt_dbbmm_variance(fishers, location_error = 25,
                               window_size = s$window_size,
                               margin      = s$margin)
} # }