Skip to contents

Optimize the xsdm log-likelihood from multiple starts (ucminfcpp)

optimize_likelihood.Rd

Runs multiple ucminfcpp optimizations from starting values generated by start_parms(), optionally in parallel. Returns one row per start with the achieved log-likelihood, convergence code, and a full math-scale parameter vector (list-column) reconstructed with mask.

Usage

optimize_likelihood(
  env_dat,
  occ,
  mask = NULL,
  num_starts = 100L,
  breadth = 1,
  parallel = FALSE,
  num_threads = RcppParallel::defaultNumThreads(),
  control = list(),
  verbose = FALSE
)

Arguments

env_dat

3D array: (locations x time x variables), no NAs.

occ

Logical or integerish 0/1 vector, length = nrow(env_dat).

mask

NULL or named numeric math-scale values to fix.

num_starts

Integer. Number of starting points. Default 100.

breadth

Scalar in [0, 1] controlling how wide the search ranges are around their (fixed, data-driven) center. breadth = 1 (the default) reproduces the pre-v0.3 behaviour that corresponded to quant_vec = c(0.1, 0.5, 0.9); breadth = 0 collapses every range to essentially a single point, equivalent to quant_vec = c(0.5 - 1e-6, 0.5, 0.5 + 1e-6). Values in between interpolate linearly.

parallel

Logical. If TRUE, distribute starts via future/furrr.

num_threads

Integer >=1. Threads used inside loglik_math. If parallel=TRUE, consider num_threads=1.

control

Named list merged into ucminfcpp control. User wins over defaults.

verbose

Logical. If TRUE, prints compact progress messages.

Value

A list with:

  • solutions: data.frame sorted by decreasing loglik, columns: start_id, loglik, convergence, and list-column full_par (complete math-scale vector).

  • best: list with par (full math-scale vector), loglik, and convergence.

Examples

optimize_likelihood(
  env_dat = example_1$env_array[1:4, , ],
  occ = example_1$occ_vec[1:4],
  num_starts = 4L
)
#> $solutions
#>   start_id        loglik convergence
#> 1        2 -3.036629e-09           1
#> 2        4 -6.764729e-08           1
#> 3        3 -1.620141e-07           1
#> 4        1 -8.471812e-07           1
#>                                                                                                  full_par
#> 1  14.2888704, 7.0353416, 3.1379368, 6.6497422, -4.0405932, 3.7333337, -17.7941687, 19.4806936, 0.3154628
#> 2          15.541108, 6.385861, -4.200487, 3.003748, 3.048523, 3.790233, -15.152765, 17.894346, -3.370279
#> 3 18.8532816, 7.1664206, 9.9134535, 7.2615993, -5.5354927, 0.7371827, -22.1025574, 17.6360544, -4.7718094
#> 4           19.450570, 5.618260, -6.350281, 5.259631, 3.858138, 1.677716, -21.033456, 22.613161, 4.543574
#> 
#> $best
#> $best$par
#>         mu1         mu2    sigltil1    sigltil2    sigrtil1    sigrtil2 
#>  14.2888704   7.0353416   3.1379368   6.6497422  -4.0405932   3.7333337 
#>        ctil          pd      o_par1 
#> -17.7941687  19.4806936   0.3154628 
#> 
#> $best$loglik
#> [1] -3.036629e-09
#> 
#> $best$convergence
#> [1] 1
#> 
#>