Eligibility gates for a candidate fit

Description

fit$converged is a single flag. It does not distinguish a genuine optimum from a run that never left its initial estimates, a parameter pinned to a declared bound, an ill-conditioned covariance step or a near-singular correlation matrix. Under automation all of those are model-selection errors: a candidate that never moved is ranked on an OFV that says nothing about the model. check_strictness() evaluates the pyDarwin-style gates and returns the reasons, so a search report can say why a candidate was excluded.

Usage

check_strictness(
  fit,
  require_converged = TRUE,
  require_covariance = FALSE,
  max_condition_number = 1000,
  max_correlation = 0.95,
  reject_on_boundary = TRUE,
  reject_init_stall = TRUE
)

Arguments

  • fit: A ferx_fit object returned by [ferx_fit](ferx_fit.qmd) or [ferx_load_fit](ferx_load_fit.qmd).
  • require_converged: Fail a fit with converged = FALSE. This already covers an internal runaway-guard hit, which demotes converged.
  • require_covariance: Fail unless the covariance step ran and produced uncertainty. A SIR fallback counts as uncertainty (it is what the user configured that fallback to produce) unless its importance weights collapsed onto a single draw, i.e. an effective sample size below 2, in which case every interval has zero width and it fails like a failed step.
  • max_condition_number: Fail when fit$condition_number (largest over smallest eigenvalue of the free-parameter correlation matrix) exceeds this. NULL disables the gate.
  • max_correlation: Fail when any off-diagonal of the covariance matrix’s correlation form exceeds this in absolute value, on the natural theta / OMEGA / SIGMA scale. NULL disables the gate.
  • reject_on_boundary: Fail a fit with a theta pinned to a declared bound - the same predicate [ferx_bootstrap](ferx_bootstrap.qmd) applies as skip_estimate_near_boundary.
  • reject_init_stall: Fail a fit that never left its initial estimates. This gate assumes a cold start from the model file’s initial estimates. A candidate warm-started from its parent’s final estimates legitimately converges within a tolerance of where it began and the fit carries nothing that separates the two, so turn this off for such a search and rely on require_converged.

Details

The defaults are pyDarwin’s posture. Set every argument to FALSE / NULL for a “rank everything, report everything” run. The two threshold gates are evaluated only when their input exists: a fit without a covariance matrix has no condition number to test. Such a gate is reported under skipped rather than being failed or silently passed; combine it with require_covariance = TRUE to make it mandatory.

Differences from the engine

ferx_core::model_selection::check_strictness() names the two parameters behind a failed correlation gate; the R fit carries the maximum as a scalar, so the message here reports the value only. A condition number that is present but NaN is reported as skipped rather than failed, since an absent one reaches R as NA too.

Seealso

[ferx_bic](ferx_bic.qmd) for the criteria a search ranks the eligible candidates on. Other diagnostics: [check_diagnostics](check_diagnostics.qmd), [ferx_bic](ferx_bic.qmd), [ferx_conddist](ferx_conddist.qmd), [ferx_cov_screen](ferx_cov_screen.qmd), [ferx_gam_screen](ferx_gam_screen.qmd), [ferx_get_warnings](ferx_get_warnings.qmd), [ferx_runlog_iters](ferx_runlog_iters.qmd), [ferx_trace](ferx_trace.qmd), [plot.ferx_bootstrap](plot.ferx_bootstrap.qmd), [plot.ferx_fit](plot.ferx_fit.qmd), [summary.ferx_fit](summary.ferx_fit.qmd)

Concept

diagnostics

Value

A list with elements:

  • passed: TRUE when no gate failed.
  • failures: Character vector, one entry per failed gate. Empty when the fit passed.
  • skipped: Character vector, one entry per gate that had no input to judge by.

Examples

ex  <- ferx_example("warfarin")
fit <- ferx_fit(ex$model, ex$data)
v <- check_strictness(fit)
if (!v$passed) print(v$failures)

# Rank everything, report nothing as ineligible.
check_strictness(fit, require_converged = FALSE, max_condition_number = NULL,
                 max_correlation = NULL, reject_on_boundary = FALSE,
                 reject_init_stall = FALSE)