Dynamic Bivariate Gaussian Bridge Variance Estimation

Estimate dynamic parallel and orthogonal movement variances using a sliding window approach with BIC-based breakpoint detection. The bivariate Gaussian bridge decomposes the movement variance into a component parallel to the direction of travel and one orthogonal to it, providing more detail about the movement process than the isotropic dBBMM.

Usage

mt_dbgb_variance(
  object,
  location_error,
  margin,
  window_size,
  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.

location_error

Per-fix horizontal 1-sigma positional error, in metres (the AEQD / projected-CRS unit). Treated as the anchor measurement-error prior in the bivariate Brownian-bridge model.

Accepted forms (identical contract to mt_dbbmm_variance()): NULL, a non-negative numeric scalar, a numeric vector of length nrow(object), a column name in object, or "auto" (probes eobs_horizontal_accuracy_estimate, then argos_lc). Multi-track inputs are sliced per-track internally; NAs are imputed via location_error_na.

margin

Integer (must be odd). Minimum locations on each side of a potential breakpoint.

window_size

Integer (must be odd). Number of locations in the sliding window.

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. One of "median" (default), "mean", "zero" (fakes certainty – use deliberately), or "approx" (linear interpolation). See mt_dbbmm_variance() for the rationale.

Value

For single-track input: an mt_dbgb_variance S3 object containing:

para_sd

Numeric vector of parallel standard deviations.

orth_sd

Numeric vector of orthogonal standard deviations.

n_estim

Number of windows each position was estimated in.

seg_interest

Logical vector of fully-covered segments.

margin, window_size

Parameters used.

track_data

Coordinates, timestamps, CRS from the input.

For multi-track input: a named list of mt_dbgb_variance objects. Tracks with too few locations are skipped with a warning.

Details

The method extends the dBBMM by decomposing the variance into a parallel component (along the direction of travel between consecutive locations) and an orthogonal component (perpendicular to it). This allows distinguishing directed movement (high parallel, low orthogonal variance) from random movement (similar variances in both directions).

A directionality index can be computed from the variances: I_d = (para - orth) / (para + orth), where values near 0 indicate Brownian motion and positive values indicate directional movement.

References

Kranstauber, B., Safi, K., & Bartumeus, F. (2014). Bivariate Gaussian bridges: directional factorization of diffusion in Brownian bridge models. Movement Ecology, 2(1), 5. doi:10.1186/2051-3933-2-5

See also

mt_dbgb_ud() to compute the UD, mt_motion_variance() to extract variances as a data.frame, mt_dbbmm_variance() for the isotropic variant.

Examples

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

fishers <- mt_read(mt_example())
fishers <- fishers[!st_is_empty(fishers), ]
f1 <- fishers[mt_track_id(fishers) == "F1", ]
f1_proj <- st_transform(f1, mt_aeqd_crs(f1))

var_obj <- mt_dbgb_variance(f1_proj, location_error = 25,
                             margin = 15, window_size = 31)
var_obj

# Directionality index
mv <- mt_motion_variance(var_obj)
I_d <- (mv$para - mv$orth) / (mv$para + mv$orth)
plot(mt_time(f1_proj), I_d, type = "l",
     xlab = "Time", ylab = "Directionality index")
} # }