Skip to contents

Dynamic Brownian Motion Variance Estimation

Source: R/dbbmm_variance_dyn.R
mt_dbbmm_variance.Rd

Estimate the dynamic Brownian motion variance using a sliding window approach with BIC-based breakpoint detection. Accepts single-track or multi-track move2 objects.

Usage

mt_dbbmm_variance(
  object,
  location_error,
  window_size,
  margin,
  parallel = FALSE,
  cores = NULL,
  location_error_na = "median"
)

Arguments

object

A move2 object in a projected coordinate system (not longitude/latitude). Use sf::st_transform(x, move2::mt_aeqd_crs(x)) to project. Both single-track and multi-track objects are accepted. Empty geometries must be removed beforehand.

location_error

Per-fix horizontal 1-sigma positional error, in metres (the AEQD / projected-CRS unit). The variance estimator treats this as the anchor measurement-error prior in the Brownian-bridge model.

Accepts:

  • NULL – no per-fix error (treats fix positions as exact, equivalent to the legacy location_error = 0).

  • a non-negative numeric scalar – uniform sigma applied to every fix.

  • a numeric vector of length nrow(object) – per-fix sigma in metres. Must match the row order of object; multi-track inputs are sliced per-track internally.

  • a single character string – name of a column in object containing per-fix sigma in metres (e.g. "eobs_horizontal_accuracy_estimate").

  • the literal "auto" – probes eobs_horizontal_accuracy_estimate first, then argos_lc (mapped via the standard CLS / Vincent et al. 2002 class-to-sigma table). gps_hdop and similar quality indicators are deliberately not auto-resolved – conversion to metres requires a sensor-specific multiplier the package cannot infer.

Negative values are rejected. NAs are imputed via location_error_na below.

window_size

Integer (must be odd). The number of locations in each sliding window. Larger values produce smoother variance estimates but miss short-term behavioural changes.

margin

Integer (must be odd). The minimum number of locations on each side of a potential breakpoint within a window. Must satisfy window_size >= 2 * margin + 1.

parallel, cores

Retained for API compatibility. Since 0.2.0 the variance kernel is implemented in C with OpenMP threading (commit bf8eb34); these arguments are no-ops at the R level. To control thread count, set the OMP_NUM_THREADS environment variable before invoking R.

location_error_na

Strategy for filling NAs in a per-fix location_error vector (occurs when some fixes carry no quality info but others do). One of "median" (default; per-track median of non-NA values – conservative central tendency, robust), "mean" (per-track mean), "zero" (treat unknown errors as zero – fakes certainty, only use when deliberately disregarding measurement error at those fixes), or "approx" (linear interpolation across positional index, with edge fill via nearest non-NA).

Value

For a single-track input: an mt_dbbmm_variance S3 object containing:

variance

Numeric vector of estimated BM variances per location (NA for positions outside the estimable range at the track margins).

in_windows

Numeric vector: number of overlapping windows each location was estimated in.

interest

Logical vector: TRUE for locations fully covered by the sliding window (maximum overlap).

break_list

Integer vector of positions where behavioural breakpoints were detected.

window_size, margin

The parameters used.

track_data

List with x, y, time_mins, n_locs, crs, timestamps from the input.

For multi-track input: a named list of mt_dbbmm_variance objects, one per track. Tracks with fewer locations than window_size are skipped with a warning.

Details

The method estimates Brownian motion variance using a leave-one-out likelihood approach within a sliding window (Horne et al. 2007). At each window position, it tests whether a single variance or two variances (split at a breakpoint) better fit the data, using BIC for model selection (Kranstauber et al. 2012). The window slides one position at a time, and the final variance for each location is the mean across all windows that covered it.

The variance estimation and breakpoint testing are implemented in C (Brent's method optimizer) for performance. The sliding window loop can optionally be parallelised across CPU cores.

References

Horne, J. S., Garton, E. O., Krone, S. M., & Lewis, J. S. (2007). Analyzing animal movements using Brownian bridges. Ecology, 88(9), 2354-2363. doi:10.1890/06-0957.1

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

See also

mt_dbbmm_ud() to compute the utilisation distribution from the variance estimate, mt_motion_variance() to extract the variance vector, mt_dbgb_variance() for the directional (bivariate) variant.

Examples

if (FALSE) { # \dontrun{
library(move2)
library(sf)

# Load and prepare example data
fishers <- mt_read(mt_example())
fishers <- fishers[!st_is_empty(fishers), ]

# Single track
f1 <- fishers[mt_track_id(fishers) == "F1", ]
f1_proj <- st_transform(f1, mt_aeqd_crs(f1))
var_obj <- mt_dbbmm_variance(f1_proj, location_error = 25,
                              window_size = 31, margin = 11)
var_obj
plot(mt_time(f1_proj), mt_motion_variance(var_obj),
     type = "l", xlab = "Time", ylab = "BM variance")

# Multiple tracks
fishers_proj <- st_transform(fishers, mt_aeqd_crs(fishers))
var_list <- mt_dbbmm_variance(fishers_proj, location_error = 25,
                               window_size = 31, margin = 11)
names(var_list)
} # }