Skip to contents

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

Source: R/optimize_likelihood.R
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_cores = max(1L, future::availableCores() - 1L),
  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_cores

Integer >=1. Cores used if parallel=TRUE. Default is the number of cores available - 1.

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        4 -3.509631e-10           1
#> 2        1 -7.628914e-10           1
#> 3        3 -3.834769e-09           1
#> 4        2 -9.142867e-07           1
#>                                                                                                           full_par
#> 1 11.62492277, 0.71440423, 5.69043983, -9.37939067, -7.19452871, 7.80048016, -26.22818144, 22.49894332, 0.03893077
#> 2         7.5414089, -0.9103606, -8.7149884, -6.5095085, 2.2091879, 6.1294833, -25.8924545, 21.9324371, -5.5786843
#> 3                 11.809805, 1.480754, 1.612405, 3.662018, -5.605882, -27.596662, -43.019076, 20.259390, -1.332216
#> 4                   13.657986, 3.692990, 5.003582, 2.972223, -7.124788, -0.599969, -24.711991, 14.598310, 5.246895
#> 
#> $best
#> $best$par
#>          mu1          mu2     sigltil1     sigltil2     sigrtil1     sigrtil2 
#>  11.62492277   0.71440423   5.69043983  -9.37939067  -7.19452871   7.80048016 
#>         ctil           pd       o_par1 
#> -26.22818144  22.49894332   0.03893077 
#> 
#> $best$loglik
#> [1] -3.509631e-10
#> 
#> $best$convergence
#> [1] 1
#> 
#>