Suggest a data-driven speed cap from the observed step-speed distribution

Companion diagnostic for mt_flag_speed_cap: reads the distribution of implied step speeds on a track, looks for a structural break separating plausible-speed fixes from extreme-speed outliers, and suggests a value for v_max. The suggestion is data-driven (entropy-valley or broken-stick break in log-speed space) and therefore still distribution-free; users can override with domain knowledge if the suggested value disagrees with species biology.

Usage

mt_suggest_speed_cap(
  x,
  method = c("auto", "entropy", "gap"),
  threshold = NULL,
  mass = NULL,
  mode = NULL,
  v_max = NULL,
  physiological_ceiling = NULL,
  plot = TRUE,
  silent = FALSE
)

Arguments

x: A move2 object.
method: Character, one of "auto" (default, matches mt_flag_speed_cap's auto path: entropy-valley first, broken-stick + dip-test fallback), "entropy" (entropy- valley only; conservative), or "gap" (broken-stick + tail- decay only; sensitive). Prior to v0.3 the default was "entropy"; the change to "auto" brings the suggester into agreement with the flagger so a user inspecting their data then calling mt_flag_speed_cap sees the same pipeline.
threshold: Numeric passed to the underlying threshold helper. Default NULL uses that helper's own default.
mass, mode: Optional. When mass is supplied (kg), an allometric prediction of the species' physiological maximum speed is derived via v_phys_estimate (Hirt et al. 2017) and overlaid on the diagnostic plot. If mode is also given (one of "flying", "running", "swimming"), a single mode-specific line is shown. If mode is left NULL, all three mode-specific lines are shown so the user can compare predictions for ambiguous cases (mode-switching species, uncertain locomotor categorisation).
v_max: Optional numeric scalar in m/s. If supplied, marks the user's own physiological cap on the diagnostic plot — the same value they would pass to mt_flag_speed_cap or mt_clean_track. When both (mass, mode) and v_max are given, the diagnostic shows three independent perspectives on the same question (empirical, allometric, user) so the user can read their congruence directly.
physiological_ceiling: Optional numeric in m/s. When supplied (typically as v_phys_estimate(mass, mode) * 1.25 – a sprint-margined per-species ceiling), the function warns when the suggested cap exceeds this value, matching mt_flag_speed_cap's warning text. When NULL, falls back to the universal mode-agnostic 55 m/s ceiling derived from Hirt 2017 (the upper-95\ flier). A suggested cap above the ceiling indicates the gap finder is detecting a structural break inside the data's outlier tail rather than between bulk and outliers.
plot: Logical. If TRUE (default), render a density diagnostic with the suggested cap overlaid as a vertical line, plus the quantile table printed to message().
silent: Logical. If FALSE (default) the function prints quantile, congruence, and triangulation diagnostics. Set TRUE to suppress.

Value

A numeric scalar: the suggested v_max in m/s, or NA_real_ if no structural break was found. Returned invisibly when plot = TRUE.

Details

K02-style spoof-boundary transitions produce speeds that sit in a yawning gap above the bulk of the distribution: on that track, 99.99\ 209 m/s with nothing in between. Any reasonable break-detector places the suggested cap in that gap. When no such gap exists (clean data without extreme-speed outliers), the function returns NA and reports that no structural break was found — the honest "no outliers" outcome.

Suggester / flagger alignment (v0.3). The suggester now applies the same pipeline as mt_flag_speed_cap's auto path: identical default method = "auto", identical break detection, identical >5% fraction-above guard, identical mode-position gate (cap must sit above the rightmost substantive mode of the speed distribution), identical 55 m/s biological-sanity ceiling warning. A user inspecting their data with mt_suggest_speed_cap() and then calling mt_flag_speed_cap(x, threshold_type = "auto") now sees a single coherent recommendation rather than two independent proposals. Pre-v0.3 versions of this function used a different default method and skipped the mode-position gate, leading to silent disagreement between the suggester and the flagger on multi-state tracks (the "rest vs flight" failure mode).

Examples

if (FALSE) { # \dontrun{
v <- mt_suggest_speed_cap(track)
if (!is.na(v)) track <- mt_flag_speed_cap(track, v_max = v)

## triangulate empirical, allometric and user estimates:
mt_suggest_speed_cap(track, mass = 5, mode = "flying", v_max = 30)
} # }