Validate generative behavior of fitted SSF or iSSF models

Runs a set of trajectory-level generative validation diagnostics on an observed track and simulated tracks. The fitted model is not required by this function: users fit and simulate from SSF or iSSF models with tools such as amt, then pass the observed and simulated tracks to gmov.

Usage

validate_ssf_generative(
  observed,
  simulated,
  metrics = c("ud", "msd", "sinuosity", "barrier"),
  barrier = NULL,
  ud_args = list(),
  msd_args = list(),
  sinuosity_args = list(),
  barrier_args = list(),
  ...
)

Arguments

observed: Observed track-like object compatible with as_gmov_track().
simulated: A list of simulated track-like objects, or a data frame with one row per simulated location and a simulation identifier column.
metrics: Character vector of metrics to compute. Supported values are "ud", "msd", "sinuosity", and "barrier".
barrier: Optional sf LINESTRING or MULTILINESTRING object used for barrier crossing validation. It is assumed to use the same planar coordinate system as the tracks.
ud_args, msd_args, sinuosity_args, barrier_args: Lists of additional arguments passed to the corresponding metric functions.
...: Passed to coercion helpers.

Value

An object of class c("gmov_generative", "list") containing the function call, track summaries, metric names, metric results, and settings.

References

Nicosia, A. (2026). Beyond the next step: A multi-criteria generative validation framework for step selection functions. Methods in Ecology and Evolution. https://doi.org/10.1111/2041-210x.70313

Examples

observed <- data.frame(x = cumsum(c(0, 1, 1, 0)), y = c(0, 0, 1, 1))
simulated <- list(
  data.frame(x = cumsum(c(0, 1, 1, 1)), y = c(0, 0, 0, 0)),
  data.frame(x = cumsum(c(0, 0, 1, 1)), y = c(0, 1, 1, 1))
)

res <- validate_ssf_generative(
  observed = observed,
  simulated = simulated,
  metrics = c("msd", "sinuosity")
)
summary(res)
#> # A tibble: 2 × 6
#>   metric    statistic_name      observed_statistic discrepancy_statistic p_value
#>   <chr>     <chr>                            <dbl>                 <dbl>   <dbl>
#> 1 msd       MSD integrated squ…              4                    4            1
#> 2 sinuosity absolute straightn…              0.926                0.0535       1
#> # ℹ 1 more variable: alternative <chr>