Gibbs sampling for stationary paths

Sample stationary trajectories from light likelihood maps and calibrated movement components. The posterior combines three components: the stationary-period light likelihood, a daily movement model (see sampling_path_default_movement()), and a route-distance prior on the interval between consecutive long periods (stap0).

Usage

sampling_path(
  tag,
  iter,
  likelihood = "map_light",
  movement = sampling_path_default_movement(),
  component_weights = c(light = 1, movement = 1, route = 1),
  route_detour = 1,
  long_period_light_only = TRUE,
  chains = 1,
  warmup = floor(iter/4),
  thin = 1,
  block_interval = 2,
  thr_likelihood = 0.99,
  thr_gs = 2000/24,
  refresh = 10,
  workers = 1,
  seed = NULL,
  quiet = FALSE
)

Arguments

tag: GeoPressureR tag object containing likelihood maps and tag_set_map parameters. Long periods are identified by tag$stap$stap0, as created by GeoPressureR::tag_stap_daily().
iter: number of Gibbs iterations per chain, including warmup.
likelihood: tag field containing the light likelihood map.
movement: daily movement model: a ground-speed kernel passed to GeoPressureR::speed2prob() and a move_stay function returning the probability of departing after a residence time. The default, sampling_path_default_movement(), is the calibrated land-bird model; call it to inspect the values and plot_movement() to plot them.
component_weights: named non-negative weights for the light, movement, and route components. Each weight multiplies that component's log probability, so the default 1 uses the calibrated components unchanged. A zero removes that component's soft contribution while retaining hard support constraints (retained light support, water mask and thr_gs).
route_detour: non-negative multiplier of the scale of the Gamma prior on route excess (see Details). 1 retains the calibrated prior, 0 targets direct routes, and values above one favour more detoured routes.
long_period_light_only: logical. TRUE applies a modular cut: at every iteration, each unknown long-period location is redrawn from its light likelihood alone, and only daily periods are updated with the movement and route components. FALSE updates long periods with light, movement and route information like daily periods. See Details.
chains: number of independent chains.
warmup: number of initial iterations to discard.
thin: interval between saved samples.
block_interval: interval between block iterations, which update each current residence segment as a single block. All other iterations are site iterations that update each eligible period once. Use 0 or Inf to disable block iterations; values must otherwise be at least 2.
thr_likelihood: retained light-likelihood mass in each stationary period. Lower values keep fewer cells and speed up the sampler, but exclude more of the light likelihood surface entirely. The default 0.99 is a conservative state-space reduction.
thr_gs: maximum ground speed, in km/h, used as the hard radius of the daily movement kernel (default 2000 / 24, i.e. 2000 km per day). Speeds below it are weighted by the movement kernel, so thr_gs is a truncation of that kernel rather than a typical speed: set it above the speeds the kernel supports. The default excludes less than 0.1% of the default kernel. Larger values increase computation; smaller values make faster transitions impossible rather than unlikely.
refresh: progress update interval in iterations.
workers: number of parallel workers for independent chains. Use 1 for sequential execution.
seed: optional random seed for reproducible chains.
quiet: whether to suppress progress messages.

Value

A data.frame with columns j, chain, stap_id, ind, lat, and lon. The result carries type = "sampling" and sampler settings in a sampling_parameters attribute.

Details

Route-distance prior. For each interval between consecutive long periods $\ell$, the route ratio $R_\ell$ is the sum of the daily great-circle displacements divided by the direct distance $D_\ell$ between the two long-period locations. The sampler adds component_weights["route"] times the log density $$\log \mathrm{Gamma}(R_\ell - 1 \mid \alpha_R,\ \mathrm{route\_detour} \times \theta_\ell),$$ with shape $\alpha_R = 1.22$ and $$\log \theta_\ell = -1.88 + 0.552\,[\log(1 + T_\ell) - 3.47] - 0.318\,[\log D_\ell - 8.15],$$ where $T_\ell$ is the interval duration in days and $D_\ell$ is in km. Both covariates are clamped to the range of the calibration data. The term is omitted when $D_\ell < 300$ km or when the interval contains at most one daily displacement.

Because route_detour multiplies the Gamma scale, the prior mean and every prior quantile of the route excess $R_\ell - 1$ scale linearly with it. For example, an interval of about 31 days with endpoints about 3,500 km apart has $\theta_\ell \approx 0.15$, i.e. a prior mean route ratio of about 1.19; route_detour = 2 raises it to about 1.37 and 0.5 lowers it to about 1.09. route_detour = 0 collapses the scale, so any detour is strongly penalised. The prior remains soft: the realised detour of the posterior also depends on the light and movement components.

Long periods and modular cut. Twilights accurately locate long periods but leave daily-period locations ambiguous. With long_period_light_only = TRUE, each unknown long-period location is redrawn independently at every iteration from its retained light likelihood (raised to component_weights["light"]), without using the movement or route components. When a redraw violates hard movement support, only the neighbouring daily locations needed to restore a feasible path are resampled. Daily periods are then updated conditionally on these long-period draws. This is a modular (cut) approximation to the joint posterior: information flows from the long-period likelihoods to the daily path, but the movement model cannot pull long-period locations away from their light likelihood. Known-location periods are always fixed.

Computational approximations. Impossible geography, such as water after masking, is removed from the state space. The arguments thr_likelihood, thr_gs and movement$approx_eps control how aggressively the sampler reduces the fixed light support and movement kernel for speed. Start with the defaults for final inference, use a smaller thr_likelihood only for explicitly approximate exploratory runs, and increase thr_likelihood or thr_gs if no movement-feasible path exists.

Examples

if (FALSE) { # \dontrun{
example_dir <- system.file("extdata", package = "GeoPathSampleR")
tag <- GeoPressureR::tag_create(
  "14OI",
  crop_start = "2015-07-17",
  crop_end = "2016-07-11",
  directory = file.path(example_dir, "data/raw-tag/14OI"),
  assert_pressure = FALSE,
  quiet = TRUE
)
tag <- GeoPressureR::twilight_create(tag)
tag <- GeoPressureR::twilight_label_read(
  tag,
  file = file.path(example_dir, "data/twilight-label/14OI-labeled.csv")
)
tag <- GeoPressureR::tag_stap_daily(
  tag,
  stap_long = file.path(example_dir, "data/stap-label/14OI.csv"),
  movement_period = "day",
  quiet = TRUE
)
tag <- GeoPressureR::tag_set_map(
  tag,
  extent = c(-20, 40, -11, 60),
  scale = 1
)
tag <- GeoPressureR::geolight_map(
  tag,
  twl_calib_adjust = 1,
  fitted_location_duration = 30,
  twl_llp = \(n) 1.5 * log(n) / n,
  quiet = TRUE
)
tag$map_light <- GeoPressureR::map_add_mask_water(tag$map_light)

paths <- sampling_path(
  tag,
  movement = sampling_path_default_movement(),
  iter = 500,
  chains = 4,
  warmup = 100,
  seed = 1,
  quiet = TRUE
)
} # }

Usage

Arguments

Value

Details

See also

Examples