Skip to contents

Dynamic Brownian Bridge Movement Model — Utilisation Distribution

Source: R/dbbmm_ud.R
mt_dbbmm_ud.Rd

Compute a utilisation distribution (UD) from a movement track using the dynamic Brownian bridge movement model. Accepts a move2 object directly (estimates variance internally), a pre-computed variance object, or a named list of variance objects for multi-track input.

Usage

mt_dbbmm_ud(
  object,
  raster = NULL,
  location_error = NULL,
  margin = 11,
  window_size = 31,
  ext = 0.5,
  dim_size = 100,
  time_step = NULL,
  verbose = TRUE,
  location_error_na = "median",
  ...
)

Arguments

object

One of:

  • A move2 object (single or multi-track, projected CRS). Variance is estimated internally via mt_dbbmm_variance().

  • An mt_dbbmm_variance object from mt_dbbmm_variance().

  • A named list of mt_dbbmm_variance objects (multi-track).

raster

A terra::SpatRaster defining the output grid, or a numeric scalar giving the cell size in map units, or NULL to auto-compute from dim_size and ext. For multi-track input with NULL, a common grid is computed from the combined extent.

location_error

Per-fix horizontal 1-sigma positional error, in metres. When object is a move2 object, this is forwarded to mt_dbbmm_variance() (see that function for the full set of accepted forms: NULL / scalar / vector / column name / "auto"). When object is an mt_dbbmm_variance object or a list of them, the default NULL re-uses the per-fix vector stored on each variance object at fit time; supplying an explicit value here overrides it.

margin

Integer (odd). Margin for variance estimation window. Only used when object is a move2 object.

window_size

Integer (odd). Window size for variance estimation. Only used when object is a move2 object.

ext

Numeric. Extension factor for the bounding box when auto-creating the raster. Increase if the C kernel reports that the grid is not large enough. Default 0.5.

dim_size

Integer. Number of cells along the longest dimension of the auto-generated raster. Higher values give finer resolution but slower computation. Default 100.

time_step

Numeric or NULL. Time step for the Brownian bridge integration, in minutes. Defaults to 1/15 of the minimum time lag. Smaller values give more precise UDs but are slower.

verbose

Logical. If TRUE, print a computational size estimate.

location_error_na

Strategy for filling NAs in a per-fix location_error vector. Forwarded to mt_dbbmm_variance() when object is a move2; ignored otherwise (the variance object already carries the imputed vector).

...

Additional arguments passed to methods.

Value

For single-track input: a terra::SpatRaster where cell values sum to 1.0, representing the utilisation distribution.

For multi-track input: a multi-layer terra::SpatRaster with one named layer per track, all on a common grid. Each layer sums to 1.0.

Details

The UD is computed by evaluating the Brownian bridge probability density at regular time steps along each segment and accumulating the density onto a raster grid. The computation is implemented in C with OpenMP parallelisation of the inner grid loops for performance.

For multi-track input, a common raster grid is computed from the combined spatial extent of all tracks, ensuring that UDs are directly comparable.

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

See also

mt_dbbmm_variance() to compute variance separately, mt_dbgb_ud() for the directional variant, mt_motion_variance() to extract variances.

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))

# One-step
ud <- mt_dbbmm_ud(f1_proj, location_error = 25,
                   window_size = 31, margin = 11, ext = 0.85)
terra::plot(ud)

# Two-step (re-use variance for different raster settings)
var_obj <- mt_dbbmm_variance(f1_proj, location_error = 25,
                              window_size = 31, margin = 11)
ud_fine <- mt_dbbmm_ud(var_obj, location_error = 25,
                        dim_size = 500, ext = 1.25)
} # }