Fit Candidate Distributions To Shift Waiting Times — fit_waiting_time

Fit and rank candidate positive continuous distributions for shift waiting times. Inputs can be numeric waiting times, data frames with a TimeToNext column, BMM bifrost_search output, or the output of shift_waiting_times(). Fitted bifrost_search inputs are accepted only for multi-regime BMM fits; numeric vectors and data frames remain generic. Because the candidate distributions have strictly positive support, inputs containing zero waits from tied or simultaneous events are rejected with an explanatory error; the zero waits remain available from shift_waiting_times() for descriptive analysis.

Usage

fit_waiting_time_distribution(
  waiting_times,
  by_lineage = FALSE,
  global_include_root_wait = TRUE,
  models = c("exp", "gamma", "weibull", "lnorm", "invgauss"),
  select_by = c("AIC", "BIC")
)

Arguments

waiting_times: Numeric vector, waiting-time data frame, shift_waiting_times object, or BMM bifrost_search output.
by_lineage: Logical; when TRUE, use pooled between-shift lineage intervals for the top-level fit instead of chronological whole-tree intervals, and also fit candidate distributions separately for each lineage with at least two waiting times.
global_include_root_wait: Logical; when fitting whole-tree global waits from a shift_waiting_times object, bifrost_search object, or global waiting-time data frame, include the initial root-to-first-shift interval. The default TRUE matches the Berv et al. (2026) reported whole-tree Weibull summary. Set to FALSE to exclude the row labeled PreviousShift == "root". Multiple such rows are ambiguous and produce an error; data without that label are unchanged.
models: Character vector of positive-support univariateML model identifiers.
select_by: Criterion used to select best models.

Value

A list of class waiting_time_distribution_fit with pooled model rankings and a long-form parameters table of fitted parameter estimates. With by_lineage = FALSE, the top-level pool contains chronological whole-tree intervals; with by_lineage = TRUE, it contains pooled between-shift lineage intervals and the result additionally includes per-lineage best-model, parameter, and exponential-rate summaries. The raw univariateML objects remain available in fits and lineage_fits.

Examples

if (requireNamespace("univariateML", quietly = TRUE)) {
  waits <- c(0.5, 0.8, 1.2, 1.9, 2.4, 3.0)
  fit_waiting_time_distribution(waits, models = c("exp", "gamma", "weibull"))
}
#> $data
#> [1] 0.5 0.8 1.2 1.9 2.4 3.0
#> 
#> $source
#> [1] "numeric"
#> 
#> $models
#> [1] "exp"     "gamma"   "weibull"
#> 
#> $rankings
#>         model  d_logLik     d_AIC     d_BIC    logLik p      AIC      BIC
#> 1     Weibull 0.0000000 0.0000000 0.0000000 -7.387155 2 18.77431 18.35783
#> 2       Gamma 0.0639259 0.1278518 0.1278518 -7.451081 2 18.90216 18.48568
#> 3 Exponential 1.5565829 1.1131657 1.3214062 -8.943737 1 19.88747 19.67923
#>        ml       univariateML
#> 1 weibull 1.956213, 1.848767
#> 2   gamma 2.981709, 1.825536
#> 3     exp          0.6122449
#> 
#> $parameters
#>     model distribution parameter  estimate n    logLik      AIC      BIC
#> 1 weibull      Weibull     shape 1.9562131 6 -7.387155 18.77431 18.35783
#> 2 weibull      Weibull     scale 1.8487667 6 -7.387155 18.77431 18.35783
#> 3   gamma        Gamma     shape 2.9817085 6 -7.451081 18.90216 18.48568
#> 4   gamma        Gamma      rate 1.8255358 6 -7.451081 18.90216 18.48568
#> 5     exp  Exponential      rate 0.6122449 6 -8.943737 19.88747 19.67923
#>       d_AIC     d_BIC  d_logLik selected selected_AIC selected_BIC
#> 1 0.0000000 0.0000000 0.0000000     TRUE         TRUE         TRUE
#> 2 0.0000000 0.0000000 0.0000000     TRUE         TRUE         TRUE
#> 3 0.1278518 0.1278518 0.0639259    FALSE        FALSE        FALSE
#> 4 0.1278518 0.1278518 0.0639259    FALSE        FALSE        FALSE
#> 5 1.1131657 1.3214062 1.5565829    FALSE        FALSE        FALSE
#>           density support_lower support_upper
#> 1 stats::dweibull             0           Inf
#> 2 stats::dweibull             0           Inf
#> 3   stats::dgamma             0           Inf
#> 4   stats::dgamma             0           Inf
#> 5     stats::dexp             0           Inf
#> 
#> $fits
#> $fits$weibull
#> Maximum likelihood estimates for the Weibull model 
#> shape  scale  
#> 1.956  1.849  
#> 
#> $fits$gamma
#> Maximum likelihood estimates for the Gamma model 
#> shape   rate  
#> 2.982  1.826  
#> 
#> $fits$exp
#> Maximum likelihood estimates for the Exponential model 
#>   rate  
#> 0.6122  
#> 
#> 
#> $selected
#>     model d_logLik d_AIC d_BIC    logLik p      AIC      BIC      ml
#> 1 Weibull        0     0     0 -7.387155 2 18.77431 18.35783 weibull
#>         univariateML
#> 1 1.956213, 1.848767
#> 
#> $selected_model
#> [1] "weibull"
#> 
#> $select_by
#> [1] "AIC"
#> 
#> $failed
#> [1] model  reason
#> <0 rows> (or 0-length row.names)
#> 
#> $by_lineage
#> [1] FALSE
#> 
#> $global_include_root_wait
#> [1] TRUE
#> 
#> $lineage
#> NULL
#> 
#> $lineage_parameters
#> NULL
#> 
#> $lineage_fits
#> NULL
#> 
#> $lambda_summary
#> NULL
#> 
#> attr(,"class")
#> [1] "waiting_time_distribution_fit" "list"