Skip to main content

Estimation methods and controlling the fit

DATA → MODEL → ESTIMATE ⇄ EVALUATE → SIMULATE → REPORT

Where you are

Initial estimates and a first fit fitted the base model with the method from its model file (FOCEI). ferx offers several estimation methods, and every method and optimizer can be tuned. This chapter shows how to choose a method, chain methods, follow what the optimizer does, and control the fit through settings. It ends with multi-start and background fits.

The data

The base model of the workflow thread, plus the smaller warfarin example for the method comparison:

base <- ferx_example("two_cpt_oral_base")
warf <- ferx_example("warfarin")
# Model copies written in this chapter go to a scratch directory, never into the installed package.
estimation_dir <- file.path(tempdir(), "estimation")
dir.create(estimation_dir, showWarnings = FALSE)

Estimation methods

method selects the estimator:

method Estimator Notes
"foce" First-order conditional estimation
"focei" FOCE with interaction The default when neither the call nor the model file sets a method
"laplace" Laplace approximation with the exact Hessian Reports a different OFV than "focei". With n_agq > 1 it becomes adaptive Gauss-Hermite quadrature
"gn", "gn_hybrid" Gauss-Newton; the hybrid finishes with a FOCEI polish step
"saem" Stochastic approximation EM Stochastic: set seed for reproducibility
"imp" Importance-sampling Monte Carlo EM With imp_eval_only = TRUE it only evaluates −2 log L and must be the last chain stage; no IOV in a [mixture] model
"impmap" Importance sampling assisted by the mode a posteriori Requires mu-referencing; no IOV in a [mixture] model
"bayes" Full MCMC Posterior summaries in fit$bayes instead of a covariance step
vi (model file only) Variational inference Set in [fit_options]; not accepted by the method argument (see below)
NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0, imp and impmap refuse a model with inter-occasion variability: impmap when the model is checked (E_IMPMAP_IOV_UNSUPPORTED), imp when the fit runs. Since then both sample the random effects and the per-occasion kappas together. With IOV, a [mixture] block is still refused (E_IMP_MIXTURE_IOV_UNSUPPORTED).

The ferx-core estimation methods pages describe each algorithm. The same warfarin model fitted with each method:

Table 6.1: Warfarin fitted with every estimation method.
methods <- c("foce", "focei", "laplace", "gn", "gn_hybrid", "saem", "imp", "impmap", "bayes")
method_fits <- lapply(methods, function(m) {
  start <- Sys.time()
  # suppress the R warnings that report overriding the model file's method
  f <- suppressWarnings(ferx_fit(warf$model, warf$data, method = m, verbose = FALSE))
  data.frame(method = m, converged = f$converged, ofv = round(f$ofv, 2),
             TVCL = signif(f$theta[["TVCL"]], 4),
             seconds = round(as.numeric(difftime(Sys.time(), start, units = "secs")), 1))
})
do.call(rbind, method_fits)
#>      method converged     ofv   TVCL seconds
#> 1      foce      TRUE -280.36 0.1330     0.0
#> 2     focei      TRUE -286.00 0.1327     0.0
#> 3   laplace      TRUE -285.97 0.1327     0.0
#> 4        gn      TRUE -286.00 0.1326     0.0
#> 5 gn_hybrid      TRUE -286.00 0.1327     0.0
#> 6      saem      TRUE -286.00 0.1327     0.0
#> 7       imp      TRUE -286.00 0.1327     3.8
#> 8    impmap      TRUE -286.00 0.1327     1.4
#> 9     bayes      TRUE -593.41 0.1329     0.7

The estimates are close, but OFVs are not comparable across methods. Each method computes the objective function under its own approximation. Compare OFVs only between fits made with the same method, as in Model development and selection.

Minimal runnable call

Pass method to override the model file. A character vector runs a chain: each stage starts from the previous stage’s estimates, and only the last stage produces the covariance step and diagnostics.

fit_chain <- ferx_fit(base$model, base$data, method = c("saem", "focei"), verbose = FALSE)
#> Warning: Model file [fit_options] sets `method = focei` but ferx_fit() argument
#> overrides it with `saem, focei`. The call-time value will be used.
fit_chain$method_chain
#> [1] "SAEM"  "FOCEI"
data.frame(converged = fit_chain$converged, ofv = fit_chain$ofv)
#>   converged       ofv
#> 1      TRUE -1185.462

Reading the result

Following the optimizer

With optimizer_trace = TRUE ferx records one row per objective evaluation. ferx_trace() returns it as a data frame:

fit <- ferx_fit(base$model, base$data, optimizer_trace = TRUE, verbose = FALSE)
trace <- ferx_trace(fit)
dim(trace)
#> [1] 347  39
head(trace[, c("iter", "method", "ofv", "wall_ms", "grad_norm", "step_norm", "optimizer")])
#>   iter method        ofv wall_ms grad_norm step_norm optimizer
#> 1    1  focei -1171.8824       9        NA        NA    bobyqa
#> 2    2  focei -1060.5261      13        NA  0.500000    bobyqa
#> 3    3  focei  2221.3810      16        NA  0.707107    bobyqa
#> 4    4  focei  -976.6897      18        NA  0.707107    bobyqa
#> 5    5  focei  -991.9928      20        NA  0.707107    bobyqa
#> 6    6  focei -1132.8166      21        NA  0.707107    bobyqa

plot() on a fit draws the trace. By default (monotonic = TRUE) the OFV panel shows the running minimum for FOCE/FOCEI, because their traces include rejected line-search trial points. log_ofv = TRUE shifts the OFV by its minimum; despite the name, it is not a log transform:

plot(fit)
Figure 6.1: Optimizer trace of the base model fit.

Run logs

ferx_runlog() writes a plain-text record of the run: model file, data summary, estimates with initial values, settings, OFV, covariance diagnostics, shrinkage and runtime. With verbose = FALSE it returns the text instead of printing it, which is convenient for saving next to the results:

log_text <- ferx_runlog(fit, verbose = FALSE)
log_lines <- strsplit(log_text, "\n")[[1]]
start_line <- grep("PARAMETER ESTIMATES", log_lines)
cat(log_lines[(start_line - 1):(start_line + 14)], sep = "\n")
#> ============================================================
#> PARAMETER ESTIMATES
#> ------------------------------------------------------------
#>   PARAMETER                            INITIAL           FINAL        SE     %RSE
#>   --------------------------------------------------------------------------------
#>   TVCL                                       5         4.42236    0.3199     7.2%
#>   TVV1                                      50         48.3315     3.075     6.4%
#>   TVQ                                       10         9.57023    0.4096     4.3%
#>   TVV2                                     100         94.2203     3.441     3.7%
#>   TVKA                                     1.2         1.25723   0.09742     7.7%
#>   ETA_CL                                   0.1        0.156455   0.04067    26.0%
#>   ETA_V1                                   0.1        0.117386   0.03158    26.9%
#>   ETA_Q                                   0.05       0.0518647   0.01417    27.3%
#>   ETA_V2                                  0.05       0.0382909   0.01044    27.3%
#>   ETA_KA                                  0.15        0.173009   0.04757    27.5%
#>   PROP_ERR                                0.02       0.0195961   0.00112     5.7%

With a trace, show_iterations = TRUE (default) adds an iteration history, shortened to its first and last 10 rows for long runs. gradient_tol sets the relative-gradient threshold used in its convergence checks. ferx_runlog_iters() prints the full iteration history:

iters <- ferx_runlog_iters(fit, verbose = FALSE)
cat(head(strsplit(iters, "\n")[[1]], 10), sep = "\n")
#> ============================================================
#> ITERATION HISTORY
#> ------------------------------------------------------------
#>   ITER            OFV           dOFV    STEP_NORM
#>   ----  -------------  -------------  -----------
#>      1       -1171.88            ---           NA
#>      2       -1060.53       +111.356          0.5
#>      3        2221.38       +3281.91       0.7071
#>      4        -976.69       -3198.07       0.7071
#>      5       -991.993       -15.3031       0.7071

The gradient at the reported estimates

The run log’s convergence checks read fit$final_gradient, the gradient of the objective at the reported parameter point, in the packed space the optimizer works in (Variability: random effects, residual error and IOV). Gradient-based optimizers report the gradient they already used. The derivative-free bobyqa has none of its own, so ferx computes one after the fit instead, which is what lets you check a converged = TRUE where it is least supported. It is the exact gradient when the model can use the analytic outer gradient (every subject in its scope, and no gradient = fd), as in warfarin, and a central finite difference otherwise. fit$final_gradient_source says which: "analytic" or "finite_difference" after a derivative-free fit, "optimizer" when the optimizer supplied the gradient, and NULL exactly when final_gradient is (see the report_final_gradient row below). Beside a gradient-based fit of the same model:

NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0 the gradient after a derivative-free fit is always a central finite difference (ferx-r NEWS for 0.4.0). The exact one came with ferx-core 93ba19fc, after that release, so the bobyqa gradient below can differ there. fit$final_gradient_source is not in that release either.

fit_bobyqa <- ferx_fit(warf$model, warf$data, settings = list(optimizer = "bobyqa"), verbose = FALSE)
fit_lbfgs <- ferx_fit(warf$model, warf$data, settings = list(optimizer = "nlopt_lbfgs"), verbose = FALSE)
data.frame(optimizer = c(fit_bobyqa$optimizer_label, fit_lbfgs$optimizer_label),
           gradient_source = c(fit_bobyqa$final_gradient_source, fit_lbfgs$final_gradient_source),
           converged = c(fit_bobyqa$converged, fit_lbfgs$converged),
           ofv = c(fit_bobyqa$ofv, fit_lbfgs$ofv),
           largest_gradient = c(max(abs(fit_bobyqa$final_gradient)), max(abs(fit_lbfgs$final_gradient))))
#>     optimizer gradient_source converged       ofv largest_gradient
#> 1      bobyqa        analytic      TRUE -280.3595     0.0017639551
#> 2 nlopt_lbfgs       optimizer      TRUE -280.3595     0.0000034036
round(fit_bobyqa$final_gradient, 4)
#> [1] -0.0018 -0.0017 -0.0002  0.0001  0.0006 -0.0002 -0.0003

The run log’s convergence check reads the same vector. It scales each component by its parameter and compares it with gradient_tol:

bobyqa_log <- strsplit(ferx_runlog(fit_bobyqa, verbose = FALSE), "\n")[[1]]
start_gradient <- grep("Relative gradient", bobyqa_log)
cat(bobyqa_log[(start_gradient - 1):(start_gradient + 1)], sep = "\n")
#>   All 7 relative gradient components satisfy |grad * param| <= 0.1.
#>   Relative gradient (grad * |param|):
#>   [ -0.0002346  -0.01276  -0.0001228  2.357e-06  5.757e-06  -6.684e-05  -3.649e-06 ]

Both fits report convergence at the same optimum: their OFVs differ by less than 0.001. The largest gradient component of the bobyqa fit, 0.002, is larger than the 0.000003 of nlopt_lbfgs, but neither is a yardstick on its own. bobyqa stops on the change in the objective and the size of its steps, not on the gradient (see its polish legs), and nlopt_lbfgs stops on its own tolerances. The run log’s check is the yardstick: every component of the bobyqa fit passes it at the default gradient_tol of 0.1. A component that fails it beside converged = TRUE is the sign to refit with a gradient-based optimizer and compare.

This gradient costs one extra gradient evaluation after the fit (for a finite difference, two objective evaluations per free parameter), and never feeds the optimizer, so the estimates are the same either way. report_final_gradient = FALSE turns it off when those evaluations are expensive, as in a large ODE model:

fit_no_grad <- ferx_fit(warf$model, warf$data,
                        settings = list(optimizer = "bobyqa", report_final_gradient = FALSE),
                        verbose = FALSE)
c(same_ofv = isTRUE(all.equal(fit_no_grad$ofv, fit_bobyqa$ofv)),
  gradient_is_null = is.null(fit_no_grad$final_gradient),
  source_is_null = is.null(fit_no_grad$final_gradient_source))
#>         same_ofv gradient_is_null   source_is_null 
#>             TRUE             TRUE             TRUE

It stays NULL for the built-in BFGS and for SAEM, which report no gradient at all.

Options that matter

Arguments of ferx_fit()

Argument Default Meaning
method NULL Estimation method or chain (above)
threads NULL Worker threads for the per-subject loops; NULL uses the model file’s threads, else the RAYON_NUM_THREADS environment variable as given, else available cores minus one, at least 1 and at most 8 (threads). ferx reads RAYON_NUM_THREADS once, at the R session’s first fit, so set it before that fit
gradient NULL Inner-loop gradient: "auto" (analytic where available) or "fd" (finite differences); NULL uses the model file
optimizer_trace FALSE Record the optimizer trace
settings NULL Named list of engine settings (tables below); a key that duplicates a dedicated argument is an error
NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0, RAYON_NUM_THREADS has no effect on the worker count. An environment that sets it, as many CI runners do (often to 1), now fits on that many workers when neither threads nor the model file sets one.

The base model’s file requests finite differences (gradient = fd). With "auto" the analytic gradient is used and the fit takes fewer objective evaluations. Pinning threads changes speed, not results:

fit_auto <- ferx_fit(base$model, base$data, gradient = "auto", verbose = FALSE)
#> Warning: Model file [fit_options] sets `gradient = fd` but ferx_fit() argument
#> overrides it with `auto`. The call-time value will be used.
fit_1thread <- ferx_fit(base$model, base$data, threads = 1, verbose = FALSE)
data.frame(
  fit = c("model file (fd)", "gradient = auto", "threads = 1"),
  gradient_used = c(fit$gradient_used, fit_auto$gradient_used, fit_1thread$gradient_used),
  evaluations = c(fit$n_iterations, fit_auto$n_iterations, fit_1thread$n_iterations),
  threads = c(fit$n_threads_used, fit_auto$n_threads_used, fit_1thread$n_threads_used),
  ofv = c(fit$ofv, fit_auto$ofv, fit_1thread$ofv)
)
#>               fit gradient_used evaluations threads       ofv
#> 1 model file (fd)            fd         386       3 -1185.462
#> 2 gradient = auto      analytic          42       3 -1185.462
#> 3     threads = 1            fd         386       1 -1185.462

Switching the gradient moved a second factor as well. With optimizer left at auto, ferx chooses the outer optimizer to suit the gradient, so the two fits did not use the same one, and the model-file fit says so in a general warning:

c(model_file = fit$optimizer_label, gradient_auto = fit_auto$optimizer_label)
#>           model_file        gradient_auto 
#>      "auto (bobyqa)" "auto (nlopt_lbfgs)"
optimizer_note <- grep("also changed the outer optimizer", fit$warnings, value = TRUE, fixed = TRUE)
cat(strwrap(optimizer_note, 90), sep = "\n")
#> gradient = fd also changed the outer optimizer: with optimizer = auto left in place it
#> resolved to bobyqa rather than the nlopt_lbfgs this model would have used under gradient
#> = auto, because auto picks the derivative-free optimizer when there is no exact analytic
#> gradient to feed a gradient-based one. Two factors moved, not one — if you are comparing
#> an fd arm against an auto arm, pin optimizer = bobyqa in both so the difference you
#> measure is the gradient.

To measure the gradient alone, pin optimizer in both fits; settings = list(optimizer = "bobyqa") on the model-file fit removes the note. fit$gradient_method_outer records the route the outer gradient took. On the covariate model of Model development and selection the route is the exact analytic gradient:

cov <- ferx_example("two_cpt_oral_cov")
fit_cov <- ferx_fit(cov$model, cov$data, verbose = FALSE)
fit_cov$gradient_method_outer
#> [1] "analytic (Dual2)"
ferx_get_warnings(fit_cov, as_df = TRUE)[, c("severity", "category")]
#>   severity           category
#> 1  warning dw_autocorrelation

Every subject got it here, so the fit carries no fallback note.

A subject outside the analytic gradient’s scope falls back to an approximation that holds its random effects fixed, and the fit then carries a general note naming how many subjects took it. That note reports the route the gradient took, not a defect in the result; if such a fit stalls, reconverge_gradient_interval (below) re-solves the random effects every N-th evaluation.

NoteChanged after ferx-r 0.4.0

With ferx-r 0.4.0, 4 of this model’s 30 subjects take the fixed-random-effect approximation, and the fit carries that general note.

Helper functions

Function Arguments
ferx_trace() fit (a fit, or a path to a trace CSV)
ferx_runlog() fit, gradient_tol (default 0.1), show_iterations (default TRUE), verbose (FALSE returns the text)
ferx_runlog_iters() fit, verbose
ferx_conddist() fit (a SAEM fit with conddist = TRUE)
ferx_fit_async() model, data, further ferx_fit() arguments, tail_n, poll_interval
ferx_collect() handle (a ferx_job), verbose
ferx_stop() handle

Settings

Everything else is set through settings = list(key = value), or with the same key in the model’s [fit_options]. The tables below are generated from the ferx-core fit options documentation and ?ferx_fit for the pinned build.

Table 6.2: Run control settings.
Setting Values Default Description
maxiter integer 500 Maximum outer loop iterations. maxiter = 0 is evaluation only: the engine runs one inner EBE solve at the initial parameters and reports the objective there with no outer optimisation — useful for scoring a fixed parameter set or computing standard errors at known estimates (with covariance = true).
optimizer_trace true, false false Write a per-iteration CSV to /tmp/ferx_trace_<pid>_<ts>.csv.
checkpoint true, false true Periodically save a resume point so a run that is interrupted (e.g. Ctrl-C, a crashed job) can be restarted from where it stopped instead of from scratch.
checkpoint_interval_secs integer 300 Minimum wall-clock seconds between checkpoint writes. Larger values reduce I/O overhead but lose more progress on an interrupt; smaller values save more often.
Table 6.3: Outer optimizer settings.
Setting Values Default Description
optimizer auto, bobyqa, slsqp, nlopt_lbfgs, mma, trust_region (plus deprecated aliases bfgs/lbfgs → nlopt_lbfgs) auto Outer-loop optimisation algorithm. Applies to method = foce / focei and to the FOCEI polish phase of method = gn_hybrid.
outer_xtol float 1e-4 Relative step tolerance: how far the optimizer’s step must shrink before it declares success.
outer_ftol float auto Relative objective tolerance: the relative OFV change below which the optimizer stops.
stagnation_guard true Stop the NLopt-based outer optimizers early once the OFV stops improving; see below.
reconverge_gradient_interval integer ≥ 0 0 How often to re-solve each subject’s inner EBE loop during the population gradient instead of holding the EBEs (η̂) and FOCE Hessian fixed.
steihaug_max_iters integer adaptive Max CG iterations for the Steihaug subproblem (only used when optimizer = trust_region).
report_final_gradient true, false true Compute a gradient at the reported estimates when the optimizer supplied none of its own, and report it as final_gradient: the exact one, with final_gradient_source = "analytic", when every subject is in the analytic gradient’s scope, else a central difference with final_gradient_source = "finite_difference".
global_search true, false false Run NLopt CRS2-LM (Controlled Random Search with Local Mutation) as a gradient-free global pre-search before the local optimizer.
global_maxeval integer 0 (auto: 30 * (n_params + 1)) Maximum evaluations of the FOCE objective during the global pre-search.
Table 6.4: Inner loop settings (individual random effects).
Setting Values Default Description
inner_optimizer auto, bfgs, lbfgs, nelder_mead auto Inner-loop (per-subject EBE) optimisation algorithm. auto uses dense BFGS, switching to limited-memory L-BFGS above 32 random effects.
inner_maxiter integer 200 Max iterations for the inner (per-subject EBE) optimizer
inner_tol float 1e-5 Gradient-norm convergence tolerance for the inner (per-subject EBE) optimizer.
inner_restarts integer 1 Guarded multi-start count for the inner (per-subject EBE) optimizer, to escape a multimodal individual objective.
inner_screen integer ≥ 0 100 Size N of the Sobol screen the cold multi-start runs before its per-coordinate seeds, to find an individual mode that lies off every axis (the flip-flop ka ↔︎ CL/V twin).
inner_twin_seed true, false true Seed the cold multi-start with the subject’s flip-flop twin before the screen: on a closed-form one_cpt_oral model whose V and KA are each log-normal on a random effect of their own, one descent from η_V, η_KA moved together by ln(k/ka).
ebe_warm_start false When an inner per-subject EBE solve fails its BFGS step and falls back to Nelder–Mead, warm-start the simplex from the BFGS partial η̂ rather than cold-starting from the prior mode η=0.
max_unconverged_frac 0.1 Fraction of subjects (with at least min_obs_for_convergence_check scored rows) allowed to have unconverged EBEs before the outer optimizer rejects the step.
min_obs_for_convergence_check 2 Subjects with fewer than this many rows are excluded from the max_unconverged_frac check (they still run normally).
ImportantNeeds ferx-r newer than 0.4.0

The inner_screen and inner_twin_seed settings are not in ferx-r 0.4.0.

Two warnings about where a fit started

Both loops can end up reporting a number that describes their starting point rather than the model, and each has its own warning.

stalled_at_init says the outer loop never left its initial estimates: no free theta, omega or sigma moved. The OFV is then the objective of the initial values, and converged need not contradict it – a fit that never moved has a flat trace to plateau on. A start that already is an optimum does not move either, so before it raises the warning ferx asks whether the start is one. It restarts the optimizer from a small perturbation of the start, and when that restart comes back to the same objective, within 0.01, it reports the restart’s verdict, sets fit$stationary_start to TRUE and raises no stalled_at_init (ferx-core warm start at an optimum). Refit a model whose [parameters] block has been rewritten with the estimates of a converged run:

fit_warf <- ferx_fit(warf$model, warf$data, verbose = FALSE)

# Rewrite the [parameters] block with a fit's own estimates. stopifnot() stops when a
# declaration is not found, rather than writing the file back unchanged.
rewrite_inits <- function(fit, path) {
  est <- fit$estimates
  lines <- readLines(warf$model)
  for (nm in c("TVCL", "TVV", "TVKA")) {
    i <- grep(paste0("theta ", nm, "\\("), lines)
    stopifnot(length(i) == 1L)
    lines[i] <- sub(paste0("theta ", nm, "\\(([^,]+),"),
                    paste0("theta ", nm, "(", format(est[nm, "estimate"], digits = 12), ","),
                    lines[i])
  }
  for (nm in c("ETA_CL", "ETA_V", "ETA_KA")) {
    i <- grep(paste0("omega ", nm, "\\s*~"), lines)
    stopifnot(length(i) == 1L)
    lines[i] <- sub("~.*$", paste0("~ ", format(est[nm, "estimate"], digits = 12)), lines[i])
  }
  i <- grep("sigma PROP_ERR\\s*~", lines)
  stopifnot(length(i) == 1L)
  lines[i] <- sub("~.*$", paste0("~ ", format(est["PROP_ERR", "estimate"], digits = 12), " (sd)"),
                  lines[i])
  writeLines(lines, path)
  lines
}

restart <- file.path(estimation_dir, "warfarin_restart.ferx")
grep("theta |omega |sigma ", rewrite_inits(fit_warf, restart), value = TRUE)
#> [1] "  theta TVCL(0.132974265988, 0.001, 10.0)"
#> [2] "  theta TVV(7.73056762534, 0.1, 500.0)"   
#> [3] "  theta TVKA(0.725258611573, 0.01, 50.0)" 
#> [4] "  omega ETA_CL ~ 0.0285972282562"         
#> [5] "  omega ETA_V  ~ 0.00957821530778"        
#> [6] "  omega ETA_KA ~ 0.34891953541"           
#> [7] "  sigma PROP_ERR ~ 0.0107480719382 (sd)"
fit_restart <- ferx_fit(restart, warf$data, settings = list(optimizer = "bobyqa"), verbose = FALSE)
fit_restart_slsqp <- ferx_fit(restart, warf$data, settings = list(optimizer = "slsqp"), verbose = FALSE)
data.frame(optimizer = c("bobyqa", "slsqp"), ofv = c(fit_restart$ofv, fit_restart_slsqp$ofv),
           converged = c(fit_restart$converged, fit_restart_slsqp$converged),
           stalled_at_init = c(fit_restart$stalled_at_init, fit_restart_slsqp$stalled_at_init),
           stationary_start = c(fit_restart$stationary_start, fit_restart_slsqp$stationary_start))
#>   optimizer       ofv converged stalled_at_init stationary_start
#> 1    bobyqa -280.3595      TRUE           FALSE             TRUE
#> 2     slsqp -280.3595      TRUE           FALSE             TRUE
restart_warnings <- ferx_get_warnings(fit_restart, as_df = TRUE)
restart_warnings[, c("severity", "category")]
#>   severity           category
#> 1  warning dw_autocorrelation

Under both optimizers the refit ends where it started, is reported converged, and carries no stalled_at_init: stationary_start says the start was checked and is an optimum, not a stall. When the restart finds a lower objective instead, the start was a stall, and it is reported as one: the fit is the run that did not move, with stalled_at_init, and a further warning names the lower objective the restart reached, so better estimates are within reach from other initial values. When the restart settles nothing either way (it ends higher or unconverged, or no maxiter budget was left for it), the fit is judged on its own, and its stalled_at_init says the start may have been an optimum. On a first fit from a model file’s own initial values it says the OFV carries no information about the model, and the remedy is different starting values, a gradient-based optimizer, or a look at final_gradient. Model development and selection gates candidates on the same verdict through reject_init_stall.

NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0 the outer loop does not check a start that it did not leave, and fit$stationary_start does not exist. The warm refits above carry stalled_at_init, and converged can be FALSE (ferx-core #2506).

The same rewrite can seed a refit from the bobyqa fit of the final-gradient comparison above, whose OFV is 9e-09 above the converged fit’s:

from_bobyqa <- file.path(estimation_dir, "warfarin_restart_bobyqa.ferx")
invisible(rewrite_inits(fit_bobyqa, from_bobyqa))
fit_from_bobyqa <- ferx_fit(from_bobyqa, warf$data, settings = list(optimizer = "bobyqa"),
                            verbose = FALSE)
data.frame(seed = c("converged fit", "bobyqa fit"),
           seed_ofv = c(fit_warf$ofv, fit_bobyqa$ofv),
           stalled_at_init = c(fit_restart$stalled_at_init, fit_from_bobyqa$stalled_at_init),
           stationary_start = c(fit_restart$stationary_start, fit_from_bobyqa$stationary_start))
#>            seed  seed_ofv stalled_at_init stationary_start
#> 1 converged fit -280.3595           FALSE             TRUE
#> 2    bobyqa fit -280.3595           FALSE             TRUE

That start is accepted as an optimum as well. The check compares objectives to within 0.01, so stationary_start says the start is as good as the optimum to that precision, not that it is the optimum itself. Compare the OFV with a fit that is known to have converged when the difference matters.

ebe_start_dependent is the inner loop’s version. It fires when re-solving the empirical Bayes estimates from a cold start at the final parameters scores materially worse than the estimates the optimizer minimised against – either the individual objective has more than one mode, or the inner loop cannot reach it from a cold start within inner_maxiter. The reported OFV is the better of the two EBE sets – the message names both – so the warning does not by itself put the estimates in doubt. What it limits is everything derived from the EBEs: IPRED, IWRES, CWRES, shrinkage and the covariance step (Diagnosing the model). Raise inner_maxiter to rule out the budget, and inner_restarts for a suspected second mode, then compare. The cold starts that inner_restarts adds begin with a quasi-random screen of inner_screen points, which finds a mode that lies off every single axis; inner_screen = 0 leaves only the per-axis starts. On a closed-form one_cpt_oral model with log-normal random effects of their own on V and KA, inner_twin_seed (true by default) first seeds them with one descent from the subject’s flip-flop twin, the mode where absorption and elimination swap roles, before the screen; on such a model the seed reaches the twin even with inner_screen = 0.

The warning also fires in the other direction, and then it does put the estimates in doubt: when the cold re-solve scores materially lower than the objective the optimizer minimised, some subjects’ EBEs stayed in a higher mode for the whole fit, so the estimates minimise the wrong objective. ferx then restarts the optimizer from that point on the remaining maxiter budget, and a restart it adopts leaves an optimizer_health note instead of this warning. Only when the gap survives, because no budget was left or the restarts ran out, is the fit reported with converged = FALSE and ebe_start_dependent, whose message says how far below the cold solve landed; refit from the reported estimates (ferx-core warning codes, when the cold solve is better). The message says which direction it is.

“Materially” is 0.05 OFV units (ferx-core #2646), so on a fit that stops at a fragile point the warning can come and go with rounding. The bundled SDE fit of Experimental features, whose end point depends on rounding in the ODE solver, raises it on some machines and not on others.

A starved inner loop is a different failure. When too many subjects’ inner loops fail to converge – a larger fraction of them than max_unconverged_frac, 0.1 by default – ferx rejects the outer trial and returns a penalty instead of an objective. A fit whose every trial is rejected this way is reported unconverged, with a critical convergence warning. The first evaluation, from the cold start, is the one most likely to fail: when the guard rejects it, ferx solves the inner loop once more at the same parameters, warm from the EBEs the cold solve found, and judges that second solve (ferx-core #2682). Cutting inner_maxiter far below its default shows how far that carries on warfarin:

fit_starved <- ferx_fit(warf$model, warf$data, settings = list(inner_maxiter = 1), verbose = FALSE)
starved_warnings <- ferx_get_warnings(fit_starved, as_df = TRUE)
rbind(default_budget = fit_warf$theta, inner_maxiter_1 = fit_starved$theta)
#>                      TVCL      TVV      TVKA
#> default_budget  0.1329743 7.730568 0.7252586
#> inner_maxiter_1 0.1329743 7.730568 0.7252565
data.frame(converged = fit_starved$converged, ofv = fit_starved$ofv, default_ofv = fit_warf$ofv)
#>   converged       ofv default_ofv
#> 1      TRUE -280.3367   -280.3595
starved_warnings[, c("severity", "category")]
#>   severity           category
#> 1  warning dw_autocorrelation

With one inner iteration per solve, the fit still converges, 0.023 OFV above the default-budget fit. That says nothing about a larger model. Leave inner_maxiter at its default unless you have a reason, and compare a reduced budget against a fit with the default before trusting it.

NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0 a rejected start is not re-solved warm, and this warfarin fit is rejected at every trial. There it converges on the penalty and reports converged = TRUE at the midpoint of its declared bounds, with no convergence warning (ferx-core #1617, fixed after that release); estimates sitting exactly on the midpoints of their bounds are the sign. Builds between that fix and #2682 report it unconverged, far above the optimum.

Choosing the outer optimizer on warfarin:

Table 6.5: The outer optimizers on warfarin.
optimizers <- c("bobyqa", "slsqp", "nlopt_lbfgs", "mma", "trust_region")
do.call(rbind, lapply(optimizers, function(o) {
  f <- ferx_fit(warf$model, warf$data, settings = list(optimizer = o), verbose = FALSE)
  data.frame(optimizer = f$optimizer_label, converged = f$converged, ofv = round(f$ofv, 4),
             evaluations = f$n_iterations)
}))
#>      optimizer converged       ofv evaluations
#> 1       bobyqa      TRUE -280.3595         248
#> 2        slsqp      TRUE -280.3595         125
#> 3  nlopt_lbfgs      TRUE -280.3595          55
#> 4          mma      TRUE -280.3595          58
#> 5 trust_region      TRUE -280.3595          42

The optimizers agree to within a small tolerance on this model. A clearly higher OFV for one optimizer would point to a convergence problem with it on your model. global_search = TRUE runs a global search before the local optimizer:

fit_global <- ferx_fit(warf$model, warf$data,
                       settings = list(global_search = TRUE, global_maxeval = 500), verbose = FALSE)
data.frame(converged = fit_global$converged, ofv = fit_global$ofv)
#>   converged       ofv
#> 1      TRUE -280.3595

Multi-start

n_starts > 1 runs several fits from perturbed starting values and keeps the converged result with the lowest OFV. Start 0 always uses the model file’s exact values; the rest are perturbed by start_sigma. It is worth reaching for on the surfaces that are prone to local minima – Michaelis-Menten elimination and its VMAX/KM ridge, a full block omega over three or more etas, or many correlated covariate parameters – and the starts share the same thread pool as the per-subject loops, so the wall time grows with the number of starts rather than staying flat – the timing below shows what it costs on this machine. Widen start_sigma when the surface is ridge-shaped rather than merely bumpy. The bundled mm_multistart model (Michaelis-Menten elimination) sets n_starts = 8 in its model file:

Table 6.6: Multi-start settings.
Setting Values Default Description
n_starts 1 Number of independent optimization runs. 1 disables multi-start (no behaviour change).
start_sigma 0.3 Log-space perturbation applied to initial theta values for starts 1..n.
multi_start_seed 42 RNG seed for the multi-start theta perturbations. Independent of seed (SAEM) so that changing the SAEM seed does not silently alter which perturbed starting points are used in FOCE multi-start runs.
mm <- ferx_example("mm_multistart")
ferx_model_get_section(mm$model, "fit_options")
#> # [fit_options]
#>   method           = focei
#>   maxiter          = 500
#>   covariance       = true
#>   n_starts         = 8
#>   start_sigma      = 0.5    # wider perturbation for a ridge-shaped surface
#>   multi_start_seed = 42

start <- Sys.time()
fit_single <- ferx_fit(mm$model, mm$data, settings = list(n_starts = 1), verbose = FALSE)
#> Warning: Model file [fit_options] sets `n_starts = 8` but ferx_fit() argument
#> overrides it with `1`. The call-time value will be used.
single_s <- as.numeric(difftime(Sys.time(), start, units = "secs"))
start <- Sys.time()
fit_multi <- ferx_fit(mm$model, mm$data, verbose = FALSE)
multi_s <- as.numeric(difftime(Sys.time(), start, units = "secs"))

data.frame(fit = c("single start", "8 starts"), ofv = c(fit_single$ofv, fit_multi$ofv),
           seconds = round(c(single_s, multi_s), 1))
#>            fit       ofv seconds
#> 1 single start -453.3985     0.3
#> 2     8 starts -453.3985     2.3
ferx_get_warnings(fit_multi, as_df = TRUE)[, c("severity", "category", "message")]
#>   severity    category
#> 1     info multi_start
#>                                                     message
#> 1 Multi-start: best result from start 4/8 (OFV = -453.3985)

On this build the single start already reaches the same OFV, so here the extra starts only confirm it, at several times the wall time. That is the outcome you hope for rather than evidence that multi-start is unnecessary – the alternative is not knowing whether the one start you ran was the good one. When a start other than the first wins, an info note in the multi_start category says which. Here one did, but only by less than the printed precision of the OFV, so the single start has the same value to every digit shown; which start comes out lowest by such a margin can differ from one machine to the next.

The two remedies for a stuck fit overlap, and ferx says how it resolves that rather than leaving you to guess. The global pre-search ignores its starting point by design, so running it on every perturbed start would overwrite the perturbation; instead it runs on start 0 only, and the remaining starts are ordinary perturbed local fits:

fit_both <- ferx_fit(warf$model, warf$data, verbose = FALSE,
                     settings = list(global_search = TRUE, global_maxeval = 200, n_starts = 2))
both_notes <- ferx_get_warnings(fit_both, as_df = TRUE)
both_notes[both_notes$category == "optimizer_config", "message"]
#> [1] "global_search = true with n_starts = 2: CRS2-LM only runs on start 0 (it ignores the starting point and would override the theta perturbation on starts 1..2)"

So the two do combine, with the division of labour the note describes: the global search looks for the basin from the file’s own values, and the perturbed starts probe around it. The note is info, not a refusal.

SAEM

The bundled warfarin_saem model sets its SAEM options in the model file. With conddist = TRUE, SAEM also samples each subject’s conditional distribution of the random effects after fitting. ferx_conddist() returns it:

Table 6.7: SAEM settings.
Setting Values Default Description
n_exploration 150 Phase 1 iterations (step size = 1)
n_convergence 250 Phase 2 iterations (step size = 1/k)
n_mh_steps auto Block Metropolis-Hastings steps per subject per iteration, or auto — the default — to size it from the dataset as 2.5 × observations per subject per η, clamped to [6, 20].
n_leapfrog 0 Leapfrog steps per HMC proposal (0 = use MH). When > 0, subjects for which HMC is unavailable (ODE model, missing analytical PK path, non-finite Ω, unsupported TV-cov path) fall back to MH using n_mh_steps proposals.
scale_adaptation robbins_monro How the MH step scales are adapted. interval is the historical rule (×1.1 / ×0.9 every adapt_interval); robbins_monro steps log δ every iteration by c·k^-0.6·(accept − target).
scale_deadband 0.15,0.60 Acceptance window lo,hi in which the robbins_monro step is skipped, leaving the scale untouched; outside it the ordinary step applies.
adapt_interval 50 Iterations between step-size adaptation, under scale_adaptation = interval.
omega_burnin 20 Initial exploration iterations during which Ω (and ΩIOV) are held at their starting values while the MH chain warms up.
mstep_damping 1.0 (off); 0.03 with iiv_on_ruv Optional exploration-phase cap on the stochastic-approximation step for the numerical θ/σ M-step (the channel that moves a theta with no ETA).
mstep_solver bobyqa Which solver moves the numerical θ/σ M-step — the channel that estimates a theta with no ETA.
mstep_draws 1 Number of E-step draws the bobyqa M-step objective is averaged over.
seed 12345 RNG seed for reproducibility
conddist false Run a post-fit conditional-distribution pass estimating each subject’s p(η_i \| y_i) by MCMC.
conddist_nsamp 200 Retained MCMC draws per subject in the conditional-distribution pass.
conddist_burnin 20 Burn-in draws discarded before accumulation, to forget the EBE-mode warm start.
conddist_keep_samples false Retain the raw per-subject draws (written to {model}-conddist-samples.csv), not just the mean/SD.
saem_kernel rw The E-step’s primary kernel. rw is the block random walk.
saem_imh_proposals 2 Independent-MH proposals per subject per iteration under saem_kernel = imh.
saem_imh_refresh 5 Iterations between rebuilds of a subject’s IMH proposal (its conditional mode and curvature, by warm-started Gauss-Newton: one η-gradient and one η-Jacobian once the mode is tracked).
saem_imh_defensive 0.05 Weight of the prior N(0, Ω) component mixed into the IMH proposal, in [0, 0.5].
saem_imh_min_obs_per_eta 2.0 Information gate for saem_kernel = imh: the fewest mean observations per subject per random effect at which the kernel runs.
ImportantNeeds ferx-r newer than 0.4.0

The saem_kernel setting and the saem_imh_proposals, saem_imh_refresh, saem_imh_defensive and saem_imh_min_obs_per_eta settings of its imh kernel are not in ferx-r 0.4.0.

ws <- ferx_example("warfarin_saem")
ferx_model_get_section(ws$model, "fit_options")
#> # [fit_options]
#>   method          = saem
#>   n_exploration   = 150
#>   n_convergence   = 250
#>   n_mh_steps      = 3
#>   omega_burnin    = 20    # iterations to hold Omega fixed while the sampler warms up
#>   adapt_interval  = 10    # MH proposal-scale adaptation cadence
#>   seed            = 12345
#>   covariance      = true
fit_saem <- ferx_fit(ws$model, ws$data, settings = list(conddist = TRUE), verbose = FALSE)
cond <- ferx_conddist(fit_saem)
cond
#> SAEM conditional distribution  (200 draws retained, 20 burn-in)
#> Distribution-based eta-shrinkage:
#>   ETA_CL         -5.6%
#>   ETA_V          -4.9%
#>   ETA_KA         -5.0%
#> 
#>    ID    ETA   COND_MEAN     COND_SD    COND_MODE
#> 1   1 ETA_CL  0.02990887 0.003426887  0.030016196
#> 2   1  ETA_V  0.06564793 0.004328043  0.065100748
#> 3   1 ETA_KA  0.37202065 0.010249928  0.370265310
#> 4   2 ETA_CL  0.01801702 0.003408088  0.017433170
#> 5   2  ETA_V -0.06369471 0.005443530 -0.064160605
#> 6   2 ETA_KA -0.41406628 0.010829274 -0.412442584
#> 7   3 ETA_CL -0.02241230 0.003868248 -0.022643863
#> 8   3  ETA_V  0.08902340 0.005141611  0.090131702
#> 9   3 ETA_KA  0.14938896 0.012759517  0.152553528
#> 10  4 ETA_CL -0.02623475 0.004283099 -0.026806979
#> 11  4  ETA_V -0.20995161 0.006625908 -0.212270745
#> 12  4 ETA_KA -0.72283755 0.012431383 -0.729949960
#> 13  5 ETA_CL -0.23116675 0.004400531 -0.232185832
#> 14  5  ETA_V -0.12157572 0.005449429 -0.122426189
#> 15  5 ETA_KA  0.48159296 0.015353154  0.481360397
#> 16  6 ETA_CL -0.00850389 0.003629024 -0.008308632
#> 17  6  ETA_V  0.06920304 0.005577278  0.069526970
#> 18  6 ETA_KA  1.24508050 0.026734245  1.246611770
#> 19  7 ETA_CL  0.29333967 0.004131073  0.291564502
#> 20  7  ETA_V  0.06578775 0.006967268  0.061817879
#> 21  7 ETA_KA -0.65928226 0.012829157 -0.665708668
#> 22  8 ETA_CL  0.27063668 0.003548004  0.270259804
#> 23  8  ETA_V -0.01749820 0.004521899 -0.018849155
#> 24  8 ETA_KA -0.03615856 0.010028578 -0.040178269
#> 25  9 ETA_CL -0.26215259 0.004567717 -0.260350659
#> 26  9  ETA_V  0.09215499 0.005901563  0.092853518
#> 27  9 ETA_KA  0.09903938 0.013892702  0.099177896
#> 28 10 ETA_CL -0.05901161 0.004367503 -0.058891821
#> 29 10  ETA_V  0.03899730 0.006177651  0.037828604
#> 30 10 ETA_KA -0.49956611 0.010584745 -0.501392022

print() on a ferx_conddist object shows the distribution-based shrinkage and the per-subject conditional mean, SD and mode. fit$saem_n_subjects_hmc reports how many subjects used HMC proposals (n_leapfrog > 0). It is not set here, because this model uses Metropolis-Hastings proposals.

How those proposals are tuned is set by three defaults. scale_adaptation = "robbins_monro" adjusts each subject’s step scale every iteration towards the target acceptance rate, but leaves it alone while the acceptance rate is inside scale_deadband. n_mh_steps = "auto" sizes the number of proposals from the data. mstep_damping is off except in models with iiv_on_ruv. interval is the older rule, which rescales only every adapt_interval iterations. Passing it with n_mh_steps = 20 and mstep_damping = 0.03 gives the previous defaults back:

saem_variants <- list(
  defaults = NULL,
  previous_defaults = list(scale_adaptation = "interval", n_mh_steps = 20, mstep_damping = 0.03),
  no_deadband = list(scale_deadband = "none")
)
# suppress the R warning that reports overriding the model file's n_mh_steps
saem_runs <- lapply(saem_variants, function(s) suppressWarnings(
  ferx_fit(ws$model, ws$data, settings = s, verbose = FALSE)))
t(sapply(saem_runs, function(f) c(ofv = f$ofv, f$theta)))
#>                         ofv      TVCL      TVV      TVKA
#> defaults          -285.9997 0.1326946 7.737729 0.8106628
#> previous_defaults -286.0020 0.1327188 7.738384 0.8110327
#> no_deadband       -286.0038 0.1327031 7.739311 0.8113093

The model file sets n_mh_steps = 3, so auto does not apply to it, and previous_defaults overrides that with 20. On this well-informed model every variant lands within 0.08% of the default estimates. The choice matters when the sampler is far from its target acceptance rate, which the ferx-core SAEM page measures on harder models.

Thetas that no random effect reaches

SAEM moves most thetas through their random effects: a typical value such as TVCL follows the mean of its eta, and a covariate exponent is updated together with the typical value it scales. A theta that no such update reaches is left to a numerical M-step instead, which ferx-core describes as noisier and able to settle away from the optimum (thetas the closed-form update cannot reach). Two settings act on that step: mstep_solver = "score_sa" replaces its derivative-free solver, and mstep_draws averages that solver’s objective over several E-step draws instead of one.

The covariate model of Model development and selection has an exponent that two updates want: THETA_WT scales both CL and V1. ferx updates the two typical values and their shared exponent in one joint M-step, and the fit’s note says so. A SAEM fit’s own OFV is a FOCE approximation, so the fits are compared on the importance-sampled −2 log-likelihood at their final estimates (Importance sampling, below), across the schedule and M-step settings:

# Fit, then evaluate the importance-sampled -2 log-likelihood at the final estimates.
# suppress the R warnings that report overriding the model file's method and covariance setting
is_fit <- function(model, method, settings = list()) {
  suppressWarnings(ferx_fit(model, cov$data, method = c(method, "imp"), covariance = FALSE,
                            settings = c(list(imp_eval_only = TRUE, imp_seed = 1), settings),
                            verbose = FALSE))
}
mstep_fits <- list(
  focei = is_fit(cov$model, "focei"),
  saem = is_fit(cov$model, "saem", list(seed = 1)),
  saem_300_700 = is_fit(cov$model, "saem", list(seed = 1, n_exploration = 300, n_convergence = 700)),
  saem_score_sa = is_fit(cov$model, "saem", list(seed = 1, mstep_solver = "score_sa")),
  saem_4_draws = is_fit(cov$model, "saem", list(seed = 1, mstep_draws = 4))
)
joint_note <- grep("joint M-step", mstep_fits$saem$warnings, value = TRUE, fixed = TRUE)
cat(strwrap(joint_note, 90), sep = "\n")
#> [SAEM] SAEM: covariate mu-references on ETA_CL (reads TVCL, THETA_WT, THETA_CRCL) and
#> ETA_V1 (reads TVV1, THETA_WT) share THETA_WT and take one joint M-step that re-centres
#> both (#1620).
t(sapply(mstep_fits, function(f) c(is_minus2ll = f$importance_sampling$minus2_log_likelihood,
                                   mc_error = f$importance_sampling$mc_standard_error,
                                   f$theta[c("TVV1", "THETA_WT", "THETA_CRCL")]))) |> round(3)
#>               is_minus2ll mc_error   TVV1 THETA_WT THETA_CRCL
#> focei           -1199.069    0.258 48.587    0.653      0.565
#> saem            -1198.811    0.255 48.765    0.627      0.570
#> saem_300_700    -1199.080    0.263 48.153    0.646      0.569
#> saem_score_sa   -1198.727    0.253 48.905    0.635      0.569
#> saem_4_draws    -1198.599    0.253 48.938    0.623      0.570

Every SAEM variant ends within 0.47 units of FOCEI on the importance-sampled objective, inside twice its Monte Carlo error, with the weight exponent between 0.62 and 0.65. On this model the M-step settings change little; they matter for a theta that is in no update at all.

NoteChanged after ferx-r 0.4.0

In ferx-r 0.4.0 the second update that wants a shared exponent is declined, which leaves TVV1 to the numerical step, and the exponent drifts towards its lower bound the longer SAEM runs (ferx-core #1620, fixed after that release). With 0.4.0, give V1 its own exponent, or use FOCEI for this model.

Laplace and adaptive quadrature

Table 6.8: Laplace and adaptive quadrature settings.
Setting Values Default Description
n_agq 1 Gauss-Hermite nodes per random effect. 1 reproduces the Laplace approximation exactly; odd values are conventional (they keep a node at the mode).
agq_eval_only (default FALSE) “laplace” only: TRUE evaluates -2 log L by adaptive quadrature at the incoming parameters instead of estimating, and must be the last stage of the chain – the deterministic counterpart of imp_eval_only.

n_agq is the number of Gauss-Hermite nodes per random effect. The cost grows as n_agq to the power of the number of etas, so higher values suit models with few random effects. agq_eval_only uses quadrature only to evaluate the likelihood at a fitted point (see the ferx-core AGQ page).

fit_lap <- ferx_fit(warf$model, warf$data, method = "laplace", verbose = FALSE)
#> Warning: Model file [fit_options] sets `method = foce` but ferx_fit() argument
#> overrides it with `laplace`. The call-time value will be used.
fit_agq <- ferx_fit(warf$model, warf$data, method = "laplace", settings = list(n_agq = 3),
                    verbose = FALSE)
#> Warning: Model file [fit_options] sets `method = foce` but ferx_fit() argument
#> overrides it with `laplace`. The call-time value will be used.
c(laplace = fit_lap$ofv, agq_3_nodes = fit_agq$ofv)
#>     laplace agq_3_nodes 
#>   -285.9703   -285.9739

Gauss-Newton

Table 6.9: Gauss-Newton settings.
Setting Values Default Description
gn_lambda Deprecated: has no effect. Gauss-Newton has used a trust region, not Levenberg-Marquardt damping, since ferx 0.1.0, so there is no damping factor to set.

gn_lambda is deprecated. Gauss-Newton takes its steps inside a trust region, so there is no damping factor to set. The key is still accepted, with any method, but it changes nothing, and the fit carries a general warning that says so:

# suppress the R warnings that report overriding the model file's method
fit_gn <- suppressWarnings(ferx_fit(base$model, base$data, method = "gn", optimizer_trace = TRUE,
                                    verbose = FALSE))
fit_gn_lambda <- suppressWarnings(ferx_fit(base$model, base$data, method = "gn",
                                           settings = list(gn_lambda = 0.5),
                                           optimizer_trace = TRUE, verbose = FALSE))
c(default = fit_gn$ofv, gn_lambda_0.5 = fit_gn_lambda$ofv)
#>       default gn_lambda_0.5 
#>     -1185.458     -1185.458
gn_warnings <- ferx_get_warnings(fit_gn_lambda, as_df = TRUE)
gn_warnings[grepl("gn_lambda", gn_warnings$message), c("category", "severity", "message")]
#>   category severity
#> 1  general  warning
#>                                                                                                                                                                                                              message
#> 1 fit option `gn_lambda` has no effect: Gauss-Newton has used a trust region, not Levenberg-Marquardt damping, since ferx 0.1.0. Remove the key from your settings; it will be rejected from the next minor release.

The trust radius is what the lm_lambda column of a Gauss-Newton trace holds: the radius a rejected step was tried with, or the radius after the update on an accepted one. The column keeps its name from an earlier algorithm; it is not a damping factor. It is NA on the trace of another method, such as the FOCEI trace above, and the run log’s iteration table heads it TR_RADIUS:

head(ferx_trace(fit_gn)[, c("iter", "method", "ofv", "step_accepted", "lm_lambda")])
#>   iter method       ofv step_accepted lm_lambda
#> 1    1     gn -1174.770             1         2
#> 2    2     gn -1176.963             1         4
#> 3    3     gn -1178.624             1         8
#> 4    4     gn -1179.895             1        10
#> 5    5     gn -1180.892             1        10
#> 6    6     gn -1182.524             1        10
NoteChanged after ferx-r 0.4.0

ferx-r 0.4.0 has no deprecation warning for gn_lambda. A Gauss-Newton fit (gn, gn_hybrid) accepts the key silently, and a fit with another method reports it as an option that method does not use. It has no effect there either. The key is rejected from the minor release after the one that adds the warning, so remove it from existing settings.

Importance sampling

Table 6.10: Importance sampling settings.
Setting Values Default Description
imp_samples 1000 Importance samples K per subject. 2000–5000 recommended for publication-quality MC SE.
imp_proposal_df 5.0 Student-t proposal degrees of freedom (≥ 1), or normal/mvn for a multivariate-normal proposal.
imp_seed 12345 RNG seed. Same seed → identical result.
imp_low_ess_threshold 0.1 Subjects with normalized ESS below this fraction get flagged in the result.
imp_iterations 200 MCEM iterations (estimator only).
imp_averaging 50 Terminal iterations averaged into the reported estimate (estimator only).
imp_auto true Adaptive sample count. When true, imp_samples is the starting count and the floor, and K follows a per-subject objective MC SE target of 0.05, up to 10000.
imp_defensive_alpha 0.0 Defensive-mixture weight (issue #528), opt-in. Each subject draws this fraction of its samples from the prior N(0, Ω) rather than the mode-centred proposal, and every sample is scored under the mixture density.
imp_eval_only false true ⇒ evaluate −2 log L at fixed parameters; must be the terminal chain stage.
imp_sobol false Estimator only: Sobol quasi-random IS draws for the MCEM E-step, the imp counterpart of impmap_sobol.
imp_adapt_passes 5 Pilot passes that adapt each subject’s proposal before a marginal −2 log L is reported, under imp_eval_only and after an estimating imp or impmap stage.
imp_max_time none Wall-clock limit on the IMP iterations, in seconds. The fit stops with its current estimate and converged: false.
ImportantNeeds ferx-r newer than 0.4.0

The imp_sobol, imp_adapt_passes and imp_max_time settings are not in ferx-r 0.4.0, nor is impmap_max_time, the same limit for IMPMAP.

A common use of imp is to evaluate the marginal likelihood at a FOCEI solution: the final stage of a chain, with imp_eval_only = TRUE. The result is in fit$importance_sampling:

fit_imp <- ferx_fit(base$model, base$data, method = c("focei", "imp"),
                    settings = list(imp_eval_only = TRUE, imp_seed = 1), verbose = FALSE)
#> Warning: Model file [fit_options] sets `method = focei` but ferx_fit() argument
#> overrides it with `focei, imp`. The call-time value will be used.
fit_imp$importance_sampling[c("minus2_log_likelihood", "mc_standard_error", "n_samples",
                              "ess_min", "ess_median")]
#> $minus2_log_likelihood
#> [1] -1185.227
#> 
#> $mc_standard_error
#> [1] 0.2617967
#> 
#> $n_samples
#> [1] 1000
#> 
#> $ess_min
#> [1] 0.3319254
#> 
#> $ess_median
#> [1] 0.7085816

?ferx_fit notes that plain "imp" re-centers its proposal from the previous iteration’s samples and can be fragile on rich data. It recommends "impmap", or a warm start such as c("focei", "imp").

Table 6.11: IMPMAP settings.
Setting Values Default Description
impmap_iterations 200 Number of MCEM iterations (parameter updates).
impmap_samples 300 Importance samples K per subject per iteration. Larger K reduces Monte-Carlo noise at linear cost.
impmap_proposal_df 4 Proposal degrees of freedom. A finite value ≥ 1 gives a heavier-tailed Student-t (default 4); normal (or mvn) gives a multivariate-normal proposal.
impmap_seed 12345 RNG seed. Same seed → identical estimates.
impmap_averaging 50 Final iterations whose parameters are averaged into the reported estimate (Monte-Carlo variance reduction).
impmap_low_ess_threshold 0.1 Subjects with normalized ESS below this fraction are flagged as poorly sampled.
impmap_trace false Logical; when TRUE, collect per-iteration parameter values into fit$impmap_trace.
impmap_mceta 0 Number of additional random starting points for per-subject MAP optimization.
impmap_sobol false Build each IS draw from an Owen-scrambled Sobol quasi-random point instead of pseudo-random numbers — the normals, the Student-t scale and the defensive-mixture component alike, so it applies to every proposal form.
impmap_auto true Adaptive sample count. When true, impmap_samples is the starting count and the floor.
iscale_min 0.1 Minimum proposal scaling factor for adaptive IS. The IS proposal covariance is multiplied by s² where s is chosen from [iscale_min, iscale_max] to maximise per-subject ESS.
iscale_max 10.0 Maximum proposal scaling factor. Same scope as iscale_min.

Bayesian estimation

Table 6.12: Bayesian estimation settings.
Setting Values Default Description
bayes_warmup Warmup (burn-in + adaptation) sweeps per chain, discarded from the posterior (default 1000).
bayes_iters Retained sampling sweeps per chain, before thinning (default 1000).
bayes_chains Number of independent chains (default 4); used for split-R-hat.
bayes_thin Keep every bayes_thin-th sampling draw (default 1).
bayes_seed Base RNG seed for the Bayes sampler. Independent of seed / saem_seed.
n_leapfrog 0 Leapfrog steps per HMC proposal (0 = use MH). When > 0, subjects for which HMC is unavailable (ODE model, missing analytical PK path, non-finite Ω, unsupported TV-cov path) fall back to MH using n_mh_steps proposals.

method = "bayes" samples the posterior with several MCMC chains and summarises the draws. On warfarin the default run converges:

# suppress the R warning that reports overriding the model file's method
fit_bayes <- suppressWarnings(ferx_fit(warf$model, warf$data, method = "bayes", verbose = FALSE))
with(fit_bayes$bayes, data.frame(parameter = param_names, mean = mean, q025 = q025, q975 = q975,
                                 rhat = rhat, ess_bulk = ess_bulk))
#>    parameter       mean        q025       q975      rhat  ess_bulk
#> 1       TVCL 0.13286358 0.117869472 0.14950892 0.9999910 3950.1267
#> 2        TVV 7.74039286 7.222298086 8.26731670 0.9999610 3810.7047
#> 3       TVKA 0.82748315 0.554507211 1.19740298 1.0004903 3757.6819
#> 4 OMEGA(1,1) 0.03554090 0.015278619 0.08245991 0.9999537 3468.8077
#> 5 OMEGA(2,2) 0.01155831 0.004909034 0.02568297 1.0012374 3120.9457
#> 6 OMEGA(3,3) 0.37953576 0.161760178 0.85034736 1.0004733 3360.2360
#> 7   PROP_ERR 0.01070177 0.009204967 0.01256083 1.0021365  872.8224
data.frame(converged = fit_bayes$converged, max_rhat = fit_bayes$bayes$max_rhat,
           chains = fit_bayes$bayes$n_chains, draws_per_chain = fit_bayes$bayes$n_draws_per_chain)
#>   converged max_rhat chains draws_per_chain
#> 1      TRUE 1.002136      4            1000

fit$bayes holds the posterior mean, median and 2.5%/97.5% quantiles, split-R-hat, effective sample sizes and Monte Carlo standard errors per parameter. R-hat compares the chains with each other: values near 1 mean they sample the same distribution, and ferx marks a run unconverged when the largest one exceeds 1.01. Here the largest is 1.002 and the smallest bulk effective sample size 873, so the posterior summaries can be used. Parameter uncertainty discusses posterior intervals as a measure of parameter uncertainty.

On the base model of this chapter, here are the default run, four times longer chains, and four times longer chains with HMC proposals for the random effects, which n_leapfrog switches on:

bayes_settings <- list(default = list(), four_times_longer = list(bayes_warmup = 4000, bayes_iters = 4000),
                       four_times_longer_hmc = list(bayes_warmup = 4000, bayes_iters = 4000, n_leapfrog = 10))
# suppress the R warnings that report overriding the model file's method
bayes_base <- lapply(bayes_settings, function(s) {
  suppressWarnings(ferx_fit(base$model, base$data, method = "bayes", settings = s, verbose = FALSE))
})
do.call(rbind, lapply(names(bayes_base), function(run) {
  b <- bayes_base[[run]]$bayes
  data.frame(run = run, draws_per_chain = b$n_draws_per_chain, converged = bayes_base[[run]]$converged,
             max_rhat = b$max_rhat, min_ess_bulk = min(b$ess_bulk))
}))
#>                     run draws_per_chain converged max_rhat min_ess_bulk
#> 1               default            1000      TRUE 1.009291     488.1455
#> 2     four_times_longer            4000      TRUE 1.002707    1728.1378
#> 3 four_times_longer_hmc            4000      TRUE 1.002713     996.2251

All three runs converge. The largest R-hat is 1.009 across the three runs. With n_leapfrog = 10 each subject’s random effects get HMC proposals instead of Metropolis-Hastings ones, which ferx offers for analytical models without IOV. They are not needed here, and at the same chain length the smallest bulk effective sample size is 996, against 1728 with the default proposals. Read max_rhat and the effective sample sizes on every run. Parameter uncertainty runs the same three settings on the covariate model.

NoteChanged after ferx-r 0.4.0

With ferx-r 0.4.0, the default run and the four times longer chains on this base model end unconverged, and only the HMC proposals converge (ferx-core #1626, fixed after that release). Check max_rhat before using posterior summaries there.

Variational inference

Variational inference fits an approximate posterior of each subject’s random effects jointly with the population parameters, by maximizing a lower bound on the likelihood (the ELBO). ferx_fit()’s method argument does not accept it:

try(ferx_fit(base$model, base$data, method = "vi", verbose = FALSE))
#> Warning: Model file [fit_options] sets `method = focei` but ferx_fit() argument
#> overrides it with `vi`. The call-time value will be used.
#> ============================================================
#>  NONLINEAR MIXED EFFECTS MODEL ESTIMATION
#> ============================================================
#>  Model: two_cpt_oral_base        Dataset: two_cpt_oral_cov
#>  Method: VI | Gradient: FD | Subjects: 30 | Obs: 300
#> 
#>  STATUS: CONVERGED   7250 iterations   28.7s
#>  OFV: NaN    AIC: NaN    BIC: NaN
#> 
#> MODEL STRUCTURE (auto-derived)
#> ------------------------------------------------------------
#>   Structural:  2-cpt oral  (TVCL, TVV1, TVQ, TVV2, TVKA)
#>   IIV:         ETA_CL, ETA_V1, ETA_Q, ETA_V2, ETA_KA
#>   IOV:         none
#>   Residual:    proportional
#> 
#> THETA
#> ------------------------------------------------------------
#> Parameter            Estimate           SE       %RSE
#> ----------------------------------------------------
#> TVCL                 4.415773     0.319978        7.2
#> TVV1                48.316810     3.056099        6.3
#> TVQ                  9.555970     0.410550        4.3
#> TVV2                94.292586     3.435419        3.6
#> TVKA                 1.259737     0.096844        7.7
#> 
#> OMEGA  (between-subject variability)
#> ------------------------------------------------------------
#>   ETA_CL               [log-normal] = 0.156940  (CV% = 41.2)  SE = 0.040919
#>   ETA_V1               [log-normal] = 0.115304  (CV% = 35.0)  SE = 0.031058
#>   ETA_Q                [log-normal] = 0.051665  (CV% = 23.0)  SE = 0.014252
#>   ETA_V2               [log-normal] = 0.037733  (CV% = 19.6)  SE = 0.010368
#>   ETA_KA               [log-normal] = 0.168988  (CV% = 42.9)  SE = 0.046492
#> 
#> SIGMA  (residual error)
#> ------------------------------------------------------------
#>   PROP_ERR         [proportional] = 0.021700  (var = 0.000471, CV% = 2.2)  SE = 0.001372  [initial specified as SD]
#> 
#> SHRINKAGE
#> ------------------------------------------------------------
#>  ETA_CL: 0.5%   ETA_V1: 2.5%   ETA_Q: 2.6%   ETA_V2: 2.3%   ETA_KA: 3.1%   EPS: 34.4% [!]
#> 
#> DIAGNOSTICS
#> ------------------------------------------------------------
#>  Covariance: computed   Cond: 1.2   DW: 3.04 [negative autocorrelation]   IWRES lag-1 r: -0.523
#> 
#> RUN INFO
#> ------------------------------------------------------------
#>  Gradient (requested): fd   (used: fd)
#>  ferx v0.4.0.9000 (core v0.4.0)
#> 
#> SETTINGS  (model file / call-time override)
#> ------------------------------------------------------------
#>   method                       focei  [model only]
#>   maxiter                      500  [model only]
#>   covariance                   true  [model only]
#>   gradient                     fd  [model only]
#> 
#> ------------------------------------------------------------
#>  4 warning  --  call ferx_get_warnings(fit) for details
#> ============================================================

It runs when the model file sets it. A copy of the base model with method = vi in [fit_options]:

vi_model <- file.path(estimation_dir, "two_cpt_oral_base_vi.ferx")
writeLines(sub("^  method     = focei", "  method     = vi", readLines(base$model)), vi_model)
invisible(ferx_model_get_section(vi_model, "fit_options"))
#> # [fit_options]
#>   method     = vi
#>   maxiter    = 500
#>   covariance = true
#>   # Finite differences rather than the default `auto`. This was a workaround
#>   # for ferx-core #1290: the analytic-gradient path used to stall at the
#>   # initial estimates on this model and dataset (`NLopt stopped: Failure` on
#>   # the first evaluation, no parameter moves), which a search then had to
#>   # reject as an init-stalled base fit. That is fixed, and both paths now
#>   # converge; `fd` is kept explicit so the example's published numbers do not
#>   # move with the gradient default.
#>   gradient   = fd
fit_vi <- ferx_fit(vi_model, base$data, verbose = FALSE)
c(method = fit_vi$method, ofv = fit_vi$ofv)
#> method    ofv 
#>   "VI"  "NaN"

The OFV is NaN by design: the ELBO is a lower bound, not −2 log-likelihood, and cannot be compared with other methods. The fit says so in a general warning. vi_final_ofv = "laplace" evaluates a Laplace OFV at the VI estimate. The vi_* settings can be passed with settings like any other:

# suppress the R warning about the model file's maxiter, which VI does not use
fit_vi_laplace <- suppressWarnings(ferx_fit(vi_model, base$data, settings = list(vi_final_ofv = "laplace"),
                                            verbose = FALSE))
rbind(vi = c(ofv = fit_vi_laplace$ofv, fit_vi_laplace$theta), focei = c(ofv = fit$ofv, fit$theta))
#>             ofv     TVCL     TVV1      TVQ     TVV2     TVKA
#> vi    -1182.477 4.415773 48.31681 9.555970 94.29259 1.259737
#> focei -1185.462 4.422360 48.33154 9.570228 94.22033 1.257227

The estimates are close to FOCEI. The ELBO itself and VI’s per-subject posterior summaries are not part of the R fit object at this build.

Table 6.13: Variational inference settings.
Setting Values Default Description
vi_iters 25000 Adam ceiling, not a fixed budget — the run stops early once the objective and the estimates have both settled.
vi_mc_samples 32 Monte-Carlo draws per subject per iteration. This sets the noise floor the settling test measures against, so it decides when the run stops as well as how noisy each step is; too few draws can settle early at the wrong answer.
vi_lr 0.02 Adam learning rate. Lower it if the trace oscillates, or if σ settles above a FOCEI/AGQ fit of the same data.
vi_grad_clip 1e4 Global-L2 gradient clip applied to every Adam step; 0 disables it.
vi_family full_rank full_rank fits a full posterior covariance per subject; mean_field fits a diagonal one — O(d) rather than O(d²).
vi_kl analytic How the KL(q ‖ N(0, Ω)) half is evaluated — analytic in closed form (only the data term is sampled) or mc.
vi_omega_update closed_form closed_form sets Ω to its exact ELBO maximizer each iteration, keeping it out of the stochastic optimization; adam learns it with everything else.
vi_sigma_update closed_form As vi_omega_update, for the residual error σ. See How σ is updated.
vi_avg_last final 25% Polyak averaging window, in iterations — the reported estimate is the mean over the final window rather than the last iterate.
vi_eta_grad auto auto uses the analytic Dual2 η-gradient where available and central finite differences where not; analytic and fd pin one route.
vi_final_ofv none none leaves ofv as NaN, because the ELBO is a lower bound and is not comparable with a FOCEI OFV; laplace computes a comparable one.
vi_seed 20240704 Seed for the common random numbers. See Reproducibility.

VI does not support non-Gaussian endpoints (time-to-event, binary). See the ferx-core variational inference page.

Running a fit in the background

In an interactive session, ferx_fit_async() starts the fit in a background process and returns a ferx_job handle immediately. It accepts the same model, data and other arguments as ferx_fit(). When R is not interactive (scripts, knitr, and so this book), it runs a normal fit and returns the result:

fit_bg <- ferx_fit_async(base$model, base$data, verbose = FALSE)
class(fit_bg)
#> [1] "ferx_fit"

The handle functions therefore only make sense interactively. They are shown here without being run:

job <- ferx_fit_async(base$model, base$data, tail_n = 6, poll_interval = 0.5)
job                          # print(): status of the background job
plot(job)                    # trace so far
job$trace_path               # path of the trace file, once written
fit <- ferx_collect(job, verbose = TRUE)   # wait, showing progress, and return the fit
ferx_stop(job)               # or: stop the job

tail_n is the number of recent trace rows shown per poll in ferx_collect(), and poll_interval is the time between polls in seconds.

Pitfalls

  • Unused options. An option that does not apply to the chosen method is ignored and reported with a general warning, which lists the options the method does use. Here the model file’s maxiter is not used by SAEM:

    fit_saem_base <- ferx_fit(base$model, base$data, method = "saem", verbose = FALSE)
    #> Warning: Model file [fit_options] sets `method = focei` but ferx_fit() argument
    #> overrides it with `saem`. The call-time value will be used.
    w_saem <- ferx_get_warnings(fit_saem_base, as_df = TRUE)
    strwrap(w_saem$message[grepl("not used by method", w_saem$message)], 80)
    #> [1] "fit option `maxiter` is not used by method `SAEM` and will be ignored."         
    #> [2] "Method-specific options for `SAEM`: adapt_interval, conddist, conddist_burnin," 
    #> [3] "conddist_keep_samples, conddist_nsamp, inner_maxiter, inner_optimizer,"         
    #> [4] "inner_tol, mstep_damping, mstep_draws, mstep_solver, n_convergence,"            
    #> [5] "n_exploration, n_leapfrog, n_mh_steps, omega_burnin, saem_conddist,"            
    #> [6] "saem_imh_defensive, saem_imh_min_obs_per_eta, saem_imh_proposals,"              
    #> [7] "saem_imh_refresh, saem_kernel, saem_mstep_damping, saem_mstep_draws,"           
    #> [8] "saem_mstep_solver, saem_n_leapfrog, saem_scale_adaptation, saem_scale_deadband,"
    #> [9] "saem_seed, scale_adaptation, scale_deadband, seed"
  • Convergence of stochastic methods. SAEM, IMP, IMPMAP and Bayes depend on the random seed and on their iteration or sample counts. Check fit$bayes$rhat and the effective sample sizes, and the ESS in fit$importance_sampling, before using the results.

  • Do not compare OFVs across methods. Refit competing models with the same method.

Warnings you may see here

See the ferx-core warnings page for the full descriptions.

  • optimizer_health (warning): the trust region collapsed or the optimizer degenerated, or a fit that stopped mid-descent or minimised against EBEs held in a higher mode was restarted from its best point, or a fit that stopped with a variance just above its internal lower guard, where the objective was still falling, was resumed from the guard (ferx-core #2832). Try a different optimizer or rescale parameters; a restarted or resumed fit that ends converged needs no action.

  • stalled_at_init (warning): no free parameter left its initial estimate, so the OFV describes the starting values rather than the model. It can arrive alongside converged = TRUE, which is why it is a warning of its own rather than a convergence warning. A start that ferx verifies as an optimum is not flagged; fit$stationary_start records that instead (above).

  • ebe_start_dependent (warning): the empirical Bayes estimates, and every diagnostic built on them, depend on where the inner loop starts. Raise inner_maxiter, or inner_restarts for a suspected second mode (above).

  • gradient_fallback (info): a slower fallback gradient or sampler path was taken.

  • mu_referencing (warning or info): mu-referencing is missing or partial. Prefer forms like CL = TVCL * exp(ETA_CL) for SAEM and Bayes.

  • optimizer_config (warning or info): a note on, or failure of, the global_search configuration.

  • multi_start (info): which start of a multi-start fit won, when it was not the first.

  • cancelled (info): the run was cancelled by the user.

  • threads (info or warning): a note on thread-count efficiency, or a warning when a threads count or RAYON_NUM_THREADS asks for more workers than there are CPUs, so the workers time-share the cores, or when RAYON_NUM_THREADS is not a positive integer and was ignored (0 means the default and raises nothing).

  • flat_parameter (warning): a theta has no effect on the objective at its initial value and was frozen there. Map it into the model or remove it.

  • init_outside_bounds (warning): an initial estimate lay outside an internal limit and was clamped before the first evaluation.

  • init_not_representable (warning): an initial estimate that the optimizer cannot represent at all, such as a positive theta started at or below the floor of the log scale it is estimated on (the message gives the value). The value is moved before the first evaluation, so the fit does not start where the file says. Here a TVKA started at 1e-12, inside its own bounds:

    tiny_start <- file.path(estimation_dir, "warfarin_tiny_ka.ferx")
    writeLines(sub("theta TVKA(1.0, 0.01, 50.0)", "theta TVKA(1e-12, 0.0, 50.0)",
                   readLines(warf$model), fixed = TRUE), tiny_start)
    fit_tiny <- ferx_fit(tiny_start, warf$data, verbose = FALSE)
    tiny_warnings <- ferx_get_warnings(fit_tiny, as_df = TRUE)
    cat(head(strwrap(tiny_warnings$message[tiny_warnings$category == "init_not_representable"], 90), 3),
        sep = "\n")
    #> W_INIT_NOT_REPRESENTABLE: TVKA is declared as 1e-12 but the optimizer sees 1.000000e-10 —
    #> ferx packs it on the log scale, and `ln` has no value at or below 0, so the packer
    #> substitutes a floor of 1e-10, which the optimizer's own box then clamps to 1.000000e-10.
    data.frame(converged = fit_tiny$converged, ofv = fit_tiny$ofv,
               stalled_at_init = fit_tiny$stalled_at_init)
    #>   converged   ofv stalled_at_init
    #> 1     FALSE 2e+21            TRUE
    unique(tiny_warnings$category[tiny_warnings$severity == "critical"])
    #> [1] "convergence"       "covariance_failed"

    Here the fit does not recover. With TVKA at 1e-10 the objective is at the divergence sentinel (W_NONFINITE_OBJECTIVE), the optimizer never leaves the start, and the fit is reported unconverged with critical warnings. Whether a fit recovers from a moved start depends on the model and the data, and a substituted start can just as well send the optimizer to another basin while still reporting convergence. Declare the start at a value the parameter can take rather than relying on the repair.

  • parameter_at_runaway_guard (warning or critical): a parameter is pinned at a hidden optimizer guard. collapse (warning) means remove or simplify it; runaway (critical) means reject the fit.

  • importance_sampling (warning): the effective sample size dropped to zero, or the proposal collapsed. Increase the samples or improve the proposal.

  • vi_bad_basin (critical): the final bound-quality check of a VI fit failed, and the fit is marked unconverged. Try new starting values, or start from another method.

Summary

  • Choose the estimator with method, chain methods with a vector, and compare OFVs only within one method.
  • Follow the optimizer with optimizer_trace = TRUE, ferx_trace(), plot(fit) and ferx_runlog().
  • Tune the fit through settings. The generated tables above list every setting that controls estimation, and ?ferx_fit documents them all.

Next: Diagnosing the model evaluates the fit.