Fit Candidate Distributions To Rates

Fit and rank candidate continuous distributions for a numeric vector of rates, a lineage-rate table, or the fitted regime rates in a bifrost_search object. bifrost_search inputs must be multi-regime BMM fits; other model families are rejected before fitting. The function is generic with respect to the candidate distribution: no distribution, including Gumbel, receives special handling unless requested through models.

Usage

fit_rate_distribution(
  x,
  log = TRUE,
  models = NULL,
  select_by = c("AIC", "BIC")
)

Arguments

x

Numeric vector, lineage-rate table, or bifrost_search object.

log

Logical; log-transform positive rate values before fitting. Lineage-rate tables with a log_lineage_rate column are treated as already log transformed when log = TRUE. When log = FALSE, lineage-rate tables must include a raw rate column rather than only log_lineage_rate.

models

Character vector of univariateML model identifiers. When NULL, a broad real-valued candidate set is used.

select_by

Criterion used to select selected_model.

Value

A list of class rate_distribution_fit with the transformed data, model rankings, a long-form parameters table of fitted parameter estimates, individual fitted objects, selected model, and failed model attempts. The raw univariateML objects remain available in fits for workflows that need package-specific methods.

Examples

if (requireNamespace("univariateML", quietly = TRUE)) {
  rates <- c(0.8, 1.1, 1.4, 1.9, 2.5, 3.1)
  fit_rate_distribution(rates, models = c("norm", "gumbel"))
}
#> $data
#> [1] -0.22314355  0.09531018  0.33647224  0.64185389  0.91629073  1.13140211
#> 
#> $original_data
#> [1] 0.8 1.1 1.4 1.9 2.5 3.1
#> 
#> $source
#> [1] "numeric"
#> 
#> $source_column
#> [1] NA
#> 
#> $transformation
#> [1] "log"
#> 
#> $log
#> [1] TRUE
#> 
#> $models
#> [1] "norm"   "gumbel"
#> 
#> $rankings
#>    model  d_logLik     d_AIC     d_BIC    logLik p      AIC      BIC     ml
#> 1 Normal 0.0000000 0.0000000 0.0000000 -3.934232 2 11.86846 11.45198   norm
#> 2 Gumbel 0.2525035 0.5050071 0.5050071 -4.186736 2 12.37347 11.95699 gumbel
#>           univariateML
#> 1 0.4830309, 0.4661568
#> 2 0.2491062, 0.4278757
#> 
#> $parameters
#>    model distribution parameter  estimate n    logLik      AIC      BIC
#> 1   norm       Normal      mean 0.4830309 6 -3.934232 11.86846 11.45198
#> 2   norm       Normal        sd 0.4661568 6 -3.934232 11.86846 11.45198
#> 3 gumbel       Gumbel        mu 0.2491062 6 -4.186736 12.37347 11.95699
#> 4 gumbel       Gumbel     sigma 0.4278757 6 -4.186736 12.37347 11.95699
#>       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.5050071 0.5050071 0.2525035    FALSE        FALSE        FALSE
#> 4 0.5050071 0.5050071 0.2525035    FALSE        FALSE        FALSE
#>               density support_lower support_upper
#> 1        stats::dnorm          -Inf           Inf
#> 2        stats::dnorm          -Inf           Inf
#> 3 extraDistr::dgumbel          -Inf           Inf
#> 4 extraDistr::dgumbel          -Inf           Inf
#> 
#> $fits
#> $fits$norm
#> Maximum likelihood estimates for the Normal model 
#>   mean      sd  
#> 0.4830  0.4662  
#> 
#> $fits$gumbel
#> Maximum likelihood estimates for the Gumbel model 
#>     mu   sigma  
#> 0.2491  0.4279  
#> 
#> 
#> $bootstrap
#> list()
#> 
#> $selected
#>    model d_logLik d_AIC d_BIC    logLik p      AIC      BIC   ml
#> 1 Normal        0     0     0 -3.934232 2 11.86846 11.45198 norm
#>           univariateML
#> 1 0.4830309, 0.4661568
#> 
#> $selected_model
#> [1] "norm"
#> 
#> $select_by
#> [1] "AIC"
#> 
#> $failed
#> [1] model  reason
#> <0 rows> (or 0-length row.names)
#> 
#> attr(,"class")
#> [1] "rate_distribution_fit" "list"