Function, option and example index
This chapter lists every ferx-r function, setting, model file block, data column, bundled example, warning category and fit object slot in the pinned build (16614e2), with the chapter that covers it. It is generated from the book’s feature inventory, the package’s help pages and the ferx-core documentation of the pinned engine.
Newer than ferx-r 0.4.0
ferx-r 0.4.0 is the last release. The pinned build is newer, and these 119 entries are not in 0.4.0 (for a fit slot: not on the result of 0.4.0’s ferx_fit()). Each chapter that uses one says so in a callout. Behaviour that changed after 0.4.0 without a new name is marked where the book relies on it.
| Kind | Name | Chapter |
|---|---|---|
| argument | arm of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | by of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | cmt of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | data of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | fit of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | model of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | n_sim of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | probs of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | ref of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | scale of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | seed of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | time of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | within of ferx_contrast_vpc() |
Model-based meta-analysis |
| argument | threads of ferx_covariance() |
Parameter uncertainty |
| argument | arm of ferx_mbma_data() |
Model-based meta-analysis |
| argument | covariates of ferx_mbma_data() |
Model-based meta-analysis |
| argument | data of ferx_mbma_data() |
Model-based meta-analysis |
| argument | index of ferx_mbma_data() |
Model-based meta-analysis |
| argument | levels of ferx_mbma_data() |
Model-based meta-analysis |
| argument | mean of ferx_mbma_data() |
Model-based meta-analysis |
| argument | n of ferx_mbma_data() |
Model-based meta-analysis |
| argument | scale of ferx_mbma_data() |
Model-based meta-analysis |
| argument | sd of ferx_mbma_data() |
Model-based meta-analysis |
| argument | se of ferx_mbma_data() |
Model-based meta-analysis |
| argument | study of ferx_mbma_data() |
Model-based meta-analysis |
| argument | time of ferx_mbma_data() |
Model-based meta-analysis |
| argument | fit of ferx_model_from_dcm() |
Experimental features |
| argument | model of ferx_model_from_dcm() |
Experimental features |
| argument | network_only of ferx_model_from_dcm() |
Experimental features |
| argument | output_model of ferx_model_from_dcm() |
Experimental features |
| argument | theta of ferx_model_from_dcm() |
Experimental features |
| argument | weights of ferx_model_from_dcm() |
Experimental features |
| argument | type of ferx_predict_survival() |
Time-to-event models |
| argument | write_model of ferx_save_fit() |
Reproducibility and sharing |
| argument | sim of ferx_sim_parameters() |
Simulating scenarios |
| argument | etas of ferx_simulate_adaptive() |
Adaptive dosing and TDM strategies |
| argument | fit of ferx_simulate_adaptive() |
Adaptive dosing and TDM strategies |
| argument | unmatched of ferx_simulate_adaptive() |
Adaptive dosing and TDM strategies |
| argument | sir_df of ferx_sir() |
Parameter uncertainty |
| argument | sir_scale of ferx_sir() |
Parameter uncertainty |
| argument | threads of ferx_sir() |
Parameter uncertainty |
| argument | fit of ferx_update_model() |
Reproducibility and sharing |
| argument | overwrite of ferx_update_model() |
Reproducibility and sharing |
| argument | path of ferx_update_model() |
Reproducibility and sharing |
| argument | by_dose of ferx_vpc_tte() |
Time-to-event models |
| argument | censoring of ferx_vpc_tte() |
Time-to-event models |
| argument | cmt of ferx_vpc_tte() |
Time-to-event models |
| argument | data of ferx_vpc_tte() |
Time-to-event models |
| argument | fit of ferx_vpc_tte() |
Time-to-event models |
| argument | grid of ferx_vpc_tte() |
Time-to-event models |
| argument | horizon of ferx_vpc_tte() |
Time-to-event models |
| argument | model of ferx_vpc_tte() |
Time-to-event models |
| argument | n_sim of ferx_vpc_tte() |
Time-to-event models |
| argument | probs of ferx_vpc_tte() |
Time-to-event models |
| argument | seed of ferx_vpc_tte() |
Time-to-event models |
| argument | strata of ferx_vpc_tte() |
Time-to-event models |
| example | mbma_placebo |
Model-based meta-analysis |
| example | nested_levels |
Model-based meta-analysis |
| function | ferx_contrast_vpc() |
Model-based meta-analysis |
| function | ferx_mbma_data() |
Model-based meta-analysis |
| function | ferx_model_from_dcm() |
Experimental features |
| function | ferx_sim_parameters() |
Simulating scenarios |
| function | ferx_update_model() |
Reproducibility and sharing |
| function | ferx_vpc_tte() |
Time-to-event models |
| fit slot | fit$bundle |
Function, option and example index |
| fit slot | fit$cov_fixed |
Function, option and example index |
| fit slot | fit$covariance_method |
Function, option and example index |
| fit slot | fit$covariance_wall_time_secs |
Function, option and example index |
| fit slot | fit$covariate_stats |
Function, option and example index |
| fit slot | fit$eval_budget_spent |
Function, option and example index |
| fit slot | fit$evaluation_only |
Function, option and example index |
| fit slot | fit$final_gradient_source |
Function, option and example index |
| fit slot | fit$held_at_bound |
Model-based meta-analysis |
| fit slot | fit$interaction |
Function, option and example index |
| fit slot | fit$iov_occasion |
Function, option and example index |
| fit slot | fit$kappa_fixed |
Function, option and example index |
| fit slot | fit$mixture_override_params |
Function, option and example index |
| fit slot | fit$mixture_overrides |
Function, option and example index |
| fit slot | fit$ode_linear_exact |
Structural models: analytical and ODE |
| fit slot | fit$omega_fixed |
Function, option and example index |
| fit slot | fit$packed_estimate |
Function, option and example index |
| fit slot | fit$population_fingerprint |
Function, option and example index |
| fit slot | fit$profiled_blocks |
Model-based meta-analysis |
| fit slot | fit$profiled_levels_at_bound |
Model-based meta-analysis |
| fit slot | fit$reader_settings |
Function, option and example index |
| fit slot | fit$scoring_settings |
Function, option and example index |
| fit slot | fit$se_mixture_overrides |
Function, option and example index |
| fit slot | fit$sigma_fixed |
Function, option and example index |
| fit slot | fit$sir_settings |
Function, option and example index |
| fit slot | fit$stationary_start |
Function, option and example index |
| fit slot | fit$status |
Diagnosing the model |
| fit slot | fit$status_label |
Diagnosing the model |
| fit slot | fit$status_reasons |
Diagnosing the model |
| fit slot | fit$subject_ids |
Function, option and example index |
| fit slot | fit$subject_summary |
Function, option and example index |
| fit slot | fit$theta_fixed |
Function, option and example index |
| fit slot | fit$theta_levels |
Model-based meta-analysis |
| fit slot | fit$uses_ode_solver |
Function, option and example index |
| fit slot | fit$warning_details |
Function, option and example index |
| S3 method | plot.ferx_contrast_vpc |
Model-based meta-analysis |
| S3 method | plot.ferx_vpc_tte |
Time-to-event models |
| S3 method | print.ferx_contrast_vpc |
Model-based meta-analysis |
| S3 method | print.ferx_mbma_data |
Model-based meta-analysis |
| S3 method | print.ferx_sim_parameters |
Simulating scenarios |
| S3 method | print.ferx_vpc_tte |
Time-to-event models |
| setting | imp_adapt_passes |
Estimation methods and controlling the fit |
| setting | imp_max_time |
Estimation methods and controlling the fit |
| setting | imp_sobol |
Estimation methods and controlling the fit |
| setting | inner_screen |
Estimation methods and controlling the fit |
| setting | inner_twin_seed |
Estimation methods and controlling the fit |
| setting | saem_imh_defensive |
Estimation methods and controlling the fit |
| setting | saem_imh_min_obs_per_eta |
Estimation methods and controlling the fit |
| setting | saem_imh_proposals |
Estimation methods and controlling the fit |
| setting | saem_imh_refresh |
Estimation methods and controlling the fit |
| setting | saem_kernel |
Estimation methods and controlling the fit |
| setting | sir_scale |
Parameter uncertainty |
| warning category | degenerate_clearance_or_volume |
Covariate modeling |
| warning category | ode_rhs_route |
Structural models: analytical and ODE |
| warning category | uncertainty_draws_skipped |
Simulating scenarios |
Functions
Help pages: ?name. Function reference on the web: ferx-r reference.
| Function | Description | Arguments | Chapter |
|---|---|---|---|
check_diagnostics() |
Structured diagnostic flags from a fit result | fit |
Initial estimates and a first fit |
check_strictness() |
Eligibility gates for a candidate fit | fit, require_converged = TRUE, require_covariance = FALSE, max_condition_number = 1000, max_correlation = 0.95, reject_on_boundary = TRUE, reject_init_stall = TRUE |
Model development and selection |
ferx_allometry() |
Allometric scaling | model = NULL, data = NULL, config = NULL, covariate = NULL, reference = NULL, parameters = NULL, exponents = NULL, estimate = FALSE, lower = NULL, upper = NULL, fit = TRUE, threads = NULL, retries = NULL, directory = NULL |
Covariate modeling |
ferx_amd() |
Automatic model development (AMD) | model = NULL, data = NULL, search_space = NULL, config = NULL, strategy = NULL, retries_on = NULL, skip = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_amd_plan() |
The AMD pipeline as planned, without fitting anything | model = NULL, data = NULL, search_space = NULL, config = NULL, strategy = NULL, retries_on = NULL, skip = NULL |
Model development and selection |
ferx_apply_selection() |
Preview data-selection filtering | data, ignore = NULL, accept = NULL, ignore_ids = NULL, excluded = FALSE, model = NULL |
Preparing and checking the analysis dataset |
ferx_bic() |
BIC variants for model selection | fit, type |
Model development and selection |
ferx_bootstrap() |
Non-parametric case bootstrap | model, data = NULL, samples = 200, seed = 1, threads = NULL, stratify_on = NULL, sample_size = NULL, update_inits = TRUE, run_base_model = TRUE, keep_covariance = FALSE, dofv = FALSE, skip_minimization_terminated = TRUE, skip_estimate_near_boundary = TRUE, skip_covariance_step_terminated = FALSE, skip_with_covstep_warnings = FALSE, ci = 95, directory = NULL, resume = FALSE, retry_failed = FALSE, progress, verbose = FALSE |
Parameter uncertainty |
ferx_bootstrap_summarize() |
Re-summarise a finished bootstrap run | directory, skip_minimization_terminated = TRUE, skip_estimate_near_boundary = TRUE, skip_covariance_step_terminated = FALSE, skip_with_covstep_warnings = FALSE, ci = 95 |
Parameter uncertainty |
ferx_calc_npde() |
Simulation-based NPDE / NPD diagnostics from a fit | fit, nsim = 1000L, seed = NULL, model = NULL, data = NULL |
Diagnosing the model |
ferx_check_init() |
Quick convergence check with an optimizer trace | model, data = NULL, method = "focei", maxiter = NULL |
Initial estimates and a first fit |
ferx_coef() |
Pull a parameter estimate or its standard error by name | fit, param = NULL |
Initial estimates and a first fit |
ferx_collect() |
Retrieve the result of a background fit | handle, verbose = TRUE |
Estimation methods and controlling the fit |
ferx_conddist() |
Per-subject SAEM conditional distribution of random effects | fit |
Estimation methods and controlling the fit |
ferx_contrast_vpc() |
Visual predictive check of a treatment contrast | fit, by, ref, within = "ID", arm = NULL, time = "TIME", cmt = NULL, n_sim = 500L, seed = 42L, scale, probs, model = NULL, data = NULL |
Model-based meta-analysis |
ferx_cov_screen() |
Quick covariate screen against individual parameters and ETAs | fit, threshold = 0.2 |
Covariate modeling |
ferx_covariance() |
Run the covariance step against an existing fit | fit, covariance_method = NULL, mu_referencing = NULL, verbose = FALSE, threads = NULL |
Parameter uncertainty |
ferx_covsearch() |
Stepwise covariate modelling (SCM) | model = NULL, data = NULL, search_space = NULL, config = NULL, algorithm = NULL, p_forward = NULL, p_backward = NULL, max_steps = NULL, adaptive_scope_reduction = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_example() |
Get paths to example model and data files | name = NULL |
A complete analysis in one chapter |
ferx_fit() |
Fit a nonlinear mixed effects model | model, data = NULL, method = NULL, covariance = NULL, verbose = NULL, bloq_method = NULL, threads = NULL, mu_referencing = NULL, sir = NULL, gradient = NULL, optimizer_trace = FALSE, scale_params = FALSE, inits_from_nca = FALSE, fd_hessian_step = NULL, settings = NULL, output = NULL, include_data = FALSE, ignore = NULL, accept = NULL, ignore_ids = NULL |
Initial estimates and a first fit |
ferx_fit_async() |
Fit a model asynchronously | model, data = NULL, tail_n = 6L, poll_interval = 0.5 |
Estimation methods and controlling the fit |
ferx_gam_screen() |
GAM-based covariate pre-screening | fit, etas = NULL, covariates = NULL, spline_df, include_linear = TRUE, shrinkage_warn = 0.3 |
Covariate modeling |
ferx_get_columns() |
Inspect column headers of a data file | data |
Preparing and checking the analysis dataset |
ferx_get_warnings() |
Structured warnings from a ferx fit | fit, as_df = FALSE |
Initial estimates and a first fit |
ferx_globalsearch() |
Global model search | model = NULL, data = NULL, search_space = NULL, config = NULL, algorithm = NULL, iiv_strategy = NULL, max_models = NULL, ga = NULL, penalties = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_iivsearch() |
Variability-structure search | model = NULL, data = NULL, search_space = NULL, config = NULL, algorithm = NULL, correlation_algorithm = NULL, as_fullblock = NULL, block_retries = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_inits_from_nca() |
Derive NCA-based starting values without fitting | model, data = NULL, method |
Initial estimates and a first fit |
ferx_iovsearch() |
Inter-occasion variability search | model = NULL, data = NULL, search_space = NULL, config = NULL, column = NULL, distribution = NULL, groups = NULL, block_retries = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_load_fit() |
Load a fit from a .fitrx bundle | path |
Reproducibility and sharing |
ferx_mbma_data() |
Build and validate a summary-level (MBMA) dataset | data, study, arm, time, mean, se = NULL, sd = NULL, n, scale, covariates = NULL, levels = NULL, index = NULL |
Model-based meta-analysis |
ferx_model() |
Create a ferx_model object | data = NULL, model = NULL, template = NULL, path = NULL, overwrite = FALSE, edit = TRUE, print = FALSE |
Writing and managing model files |
ferx_model_edit() |
Open a ferx model file in an editor | path, dest = ".", overwrite = FALSE, save_as = NULL, .editor |
Writing and managing model files |
ferx_model_from_dcm() |
Export a fitted deep compartment model as a plain population PK model | model, fit = NULL, output_model = NULL, weights, network_only = FALSE, theta = NULL |
Experimental features |
ferx_model_get_section() |
Get a section from a ferx model | x, section, strip = FALSE |
Writing and managing model files |
ferx_model_inspect() |
Inspect the structure of a ferx model file | path |
Writing and managing model files |
ferx_model_set_section() |
Set a section in a ferx model | x, section, lines |
Writing and managing model files |
ferx_model_show() |
Display a ferx model file in the console | path |
Writing and managing model files |
ferx_model_to_frem() |
Prepare a FREM (Full Random Effects Model) dataset and model | model, data = NULL, covariates = NULL, output_dir = NULL, output_model = NULL, output_data = NULL, fit = NULL |
Covariate modeling |
ferx_model_validate() |
Validate a ferx model file for syntax and structural errors | path, data = NULL |
Writing and managing model files |
ferx_modelsearch() |
Structural PK model search | model = NULL, data = NULL, search_space = NULL, config = NULL, algorithm = NULL, iiv_strategy = NULL, rank = NULL, cutoff = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_predict() |
Population predictions from a NLME model | model, data = NULL, fit = NULL |
Simulating scenarios |
ferx_predict_survival() |
Survival-function predictions for time-to-event endpoints | model, data = NULL, times, fit = NULL, type |
Time-to-event models |
ferx_runlog() |
Run log for a ferx fit | fit, gradient_tol = 0.1, show_iterations = TRUE, verbose = TRUE |
Estimation methods and controlling the fit |
ferx_runlog_iters() |
Print the full optimizer iteration history for a ferx fit | fit, verbose = TRUE |
Estimation methods and controlling the fit |
ferx_ruvsearch() |
Residual-error model search | model = NULL, data = NULL, config = NULL, groups = NULL, p_value = NULL, skip = NULL, max_iter = NULL, cwres_prescreen = NULL, threads = NULL, retries = NULL, directory = NULL, resume = FALSE, progress |
Model development and selection |
ferx_save_fit() |
Save a ferx fit to a portable .fitrx bundle | fit, output, include_data = FALSE, write_model = FALSE |
Reproducibility and sharing |
ferx_se() |
Pull a parameter estimate or its standard error by name | fit, param = NULL |
Initial estimates and a first fit |
ferx_search_config() |
Load and validate a .ferxsearch search configuration | path |
Model development and selection |
ferx_search_coverage() |
Coverage of a search space against what the engine can express | space |
Model development and selection |
ferx_search_results() |
Read a search run’s table | directory, partial = NULL, type |
Model development and selection |
ferx_search_space() |
Parse and expand an MFL search space | mfl, model = NULL, data = NULL |
Model development and selection |
ferx_sim_parameters() |
Per-subject drawn parameters of a simulation | sim |
Simulating scenarios |
ferx_simulate() |
Simulate from a NLME model | model, data = NULL, n_sim = 1L, seed = 42L, fit = NULL, match = FALSE, horizon = NULL |
Simulation-based evaluation: VPC |
ferx_simulate_adaptive() |
Simulate state-reactive (adaptive / feedback) dosing | model, data = NULL, n_sim = 1L, seed = 42L, verify = TRUE, max_decisions = 0L, fit = NULL, etas = NULL, unmatched |
Adaptive dosing and TDM strategies |
ferx_simulate_with_uncertainty() |
Simulate with parameter-uncertainty propagation | model, data, fit, n_uncertainty_draws = 100L, n_sim_per_draw = 1L, method, seed = 42L |
Simulating scenarios |
ferx_sir() |
Run SIR against an existing fit | fit, sir_samples = NULL, sir_resamples = NULL, sir_seed = NULL, sir_keep_samples = NULL, verbose = FALSE, sir_scale = NULL, sir_df = NULL, threads = NULL |
Parameter uncertainty |
ferx_stop() |
Stop a background fit | handle |
Estimation methods and controlling the fit |
ferx_trace() |
Read the optimizer trace from a ferx fit | fit |
Estimation methods and controlling the fit |
ferx_update_model() |
Write a fitted model with its final estimates as initial values | fit, path = NULL, overwrite = FALSE |
Reproducibility and sharing |
ferx_vpc_tte() |
Kaplan-Meier visual predictive check for a time-to-event model | model, data = NULL, n_sim = 200L, seed = 42L, fit = NULL, strata = NULL, by_dose = FALSE, censoring, cmt = NULL, horizon = NULL, probs, grid = "auto" |
Time-to-event models |
ferx_xpose() |
Build an object from a ferx fit | fit, backend, continuous = NULL, categorical = NULL, runno = 1L, iterations = TRUE |
Diagnosing the model |
S3 methods
Fit settings
Keys for ferx_fit(settings = list(...)) and the [fit_options] block. The chapter column points at the section that uses the key; the ferx-core fit options page gives the full semantics. A blank Values cell means the key takes a free value (a number, a name or a list) rather than a fixed set; a blank Meaning means the pinned engine documents the key only in terms of other software, which this book does not quote.
| Setting | Values | Default | Meaning | Chapter |
|---|---|---|---|---|
accept |
Character vector of filter expressions. A record is kept only when all conditions pass; excluded if any fail. | Preparing and checking the analysis dataset | ||
adapt_interval |
50 |
Iterations between step-size adaptation, under scale_adaptation = interval. |
Estimation methods and controlling the fit | |
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. | Estimation methods and controlling the fit | ||
analytic_cov_hessian |
true, false |
true |
Use the exact analytic R-matrix for the covariance step when the model is in scope, instead of the finite-difference-of-OFV Hessian. | Parameter uncertainty |
bayes_chains |
Number of independent chains (default 4); used for split-R-hat. | Estimation methods and controlling the fit | ||
bayes_iters |
Retained sampling sweeps per chain, before thinning (default 1000). | Estimation methods and controlling the fit | ||
bayes_seed |
Base RNG seed for the Bayes sampler. Independent of seed / saem_seed. | Estimation methods and controlling the fit | ||
bayes_thin |
Keep every bayes_thin-th sampling draw (default 1). | Estimation methods and controlling the fit | ||
bayes_warmup |
Warmup (burn-in + adaptation) sweeps per chain, discarded from the posterior (default 1000). | Estimation methods and controlling the fit | ||
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. |
Estimation methods and controlling the fit |
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. | Estimation methods and controlling the fit |
conddist |
false |
Run a post-fit conditional-distribution pass estimating each subject’s p(η_i \| y_i) by MCMC. |
Estimation methods and controlling the fit | |
conddist_burnin |
20 |
Burn-in draws discarded before accumulation, to forget the EBE-mode warm start. | Estimation methods and controlling the fit | |
conddist_keep_samples |
false |
Retain the raw per-subject draws (written to {model}-conddist-samples.csv), not just the mean/SD. |
Estimation methods and controlling the fit | |
conddist_nsamp |
200 |
Retained MCMC draws per subject in the conditional-distribution pass. | Estimation methods and controlling the fit | |
cov_inner_tol |
float | inner_tol (LTBS: min(inner_tol, 1e-8)) |
Inner EBE-reconvergence tolerance used only by the covariance step, decoupled from inner_tol. |
Parameter uncertainty |
covariance_fallback |
none, sir |
none |
What to do when the covariance Hessian is non-PD, whether R is analytic or finite-difference. |
Parameter uncertainty |
covariance_method |
r, s, rsr |
r |
The estimator that produced cov_matrix and the standard errors: “r”, “s” or “rsr”, the [fit_options] token (ferx-core #1382). | Parameter uncertainty |
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. | Estimation methods and controlling the fit | |
fd_hessian_step |
float | 1e-2 |
Initial relative step size for the finite-difference Hessian used in the covariance step. | Parameter uncertainty |
frem_predictions |
Covariate modeling | |||
frem_rao_blackwell |
true |
FREM only: Rao-Blackwellise the covariate ETAs (integrate them analytically, importance-sample only the PK ETAs). | Covariate modeling | |
frem_sigma |
Covariate modeling | |||
global_maxeval |
integer | 0 (auto: 30 * (n_params + 1)) |
Maximum evaluations of the FOCE objective during the global pre-search. | Estimation methods and controlling the fit |
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. | Estimation methods and controlling the fit |
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. | Estimation methods and controlling the fit | ||
ignore |
Character vector of filter expressions that exclude a record when the expression evaluates to true. | Preparing and checking the analysis dataset | ||
ignore_subjects |
Preparing and checking the analysis dataset | |||
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. |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
imp_averaging |
50 |
Terminal iterations averaged into the reported estimate (estimator only). | Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
imp_eval_only |
false |
true ⇒ evaluate −2 log L at fixed parameters; must be the terminal chain stage. |
Estimation methods and controlling the fit | |
imp_iterations |
200 |
MCEM iterations (estimator only). | Estimation methods and controlling the fit | |
imp_low_ess_threshold |
0.1 |
Subjects with normalized ESS below this fraction get flagged in the result. | Estimation methods and controlling the fit | |
imp_max_time |
none | Wall-clock limit on the IMP iterations, in seconds. The fit stops with its current estimate and converged: false. |
Estimation methods and controlling the fit | |
imp_proposal_df |
5.0 |
Student-t proposal degrees of freedom (≥ 1), or normal/mvn for a multivariate-normal proposal. |
Estimation methods and controlling the fit | |
imp_samples |
1000 |
Importance samples K per subject. 2000–5000 recommended for publication-quality MC SE. | Estimation methods and controlling the fit | |
imp_seed |
12345 |
RNG seed. Same seed → identical result. | Estimation methods and controlling the fit | |
imp_sobol |
false |
Estimator only: Sobol quasi-random IS draws for the MCEM E-step, the imp counterpart of impmap_sobol. |
Estimation methods and controlling the fit | |
impmap_auto |
true |
Adaptive sample count. When true, impmap_samples is the starting count and the floor. |
Estimation methods and controlling the fit | |
impmap_averaging |
50 |
Final iterations whose parameters are averaged into the reported estimate (Monte-Carlo variance reduction). | Estimation methods and controlling the fit | |
impmap_iterations |
200 |
Number of MCEM iterations (parameter updates). | Estimation methods and controlling the fit | |
impmap_low_ess_threshold |
0.1 |
Subjects with normalized ESS below this fraction are flagged as poorly sampled. | Estimation methods and controlling the fit | |
impmap_mceta |
0 |
Number of additional random starting points for per-subject MAP optimization. | Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
impmap_samples |
300 |
Importance samples K per subject per iteration. Larger K reduces Monte-Carlo noise at linear cost. | Estimation methods and controlling the fit | |
impmap_seed |
12345 |
RNG seed. Same seed → identical estimates. | Estimation methods and controlling the fit | |
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. | Estimation methods and controlling the fit | |
impmap_trace |
false |
Logical; when TRUE, collect per-iteration parameter values into fit$impmap_trace. | Estimation methods and controlling the fit | |
inits_from_nca |
true, false, nca, nca_sweep, nca_ebe |
false |
Derive NCA-based starting values from the data before the optimizer loop. | Initial estimates and a first fit |
inner_maxiter |
integer | 200 |
Max iterations for the inner (per-subject EBE) optimizer | Estimation methods and controlling the fit |
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. |
Estimation methods and controlling the fit |
inner_restarts |
integer | 1 |
Guarded multi-start count for the inner (per-subject EBE) optimizer, to escape a multimodal individual objective. | Estimation methods and controlling the fit |
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). |
Estimation methods and controlling the fit |
inner_tol |
float | 1e-5 |
Gradient-norm convergence tolerance for the inner (per-subject EBE) optimizer. | Estimation methods and controlling the fit |
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). |
Estimation methods and controlling the fit |
iov_column |
string | — | Name of the occasion column in the dataset (e.g. OCC). Supplies occasions when the model uses kappa or block_kappa declarations. |
Variability: random effects, residual error and IOV |
iov_occasion |
column, dose, time(t₁, …) |
column |
Derive the IOV occasion partition from the model instead of a data column. | Variability: random effects, residual error and IOV |
iscale_max |
10.0 |
Maximum proposal scaling factor. Same scope as iscale_min. |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
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). |
Estimation methods and controlling the fit |
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). |
Estimation methods and controlling the fit | |
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). | Estimation methods and controlling the fit | |
mstep_draws |
1 |
Number of E-step draws the bobyqa M-step objective is averaged over. |
Estimation methods and controlling the fit | |
mstep_solver |
bobyqa |
Which solver moves the numerical θ/σ M-step — the channel that estimates a theta with no ETA. | Estimation methods and controlling the fit | |
mu_referencing |
true, false |
true |
Re-centre inner-loop ETA estimates on the current population mean (auto-detected from [individual_parameters]). |
Variability: random effects, residual error and IOV |
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. |
Estimation methods and controlling the fit | |
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). |
Estimation methods and controlling the fit | |
n_convergence |
250 |
Phase 2 iterations (step size = 1/k) | Estimation methods and controlling the fit | |
n_exploration |
150 |
Phase 1 iterations (step size = 1) | Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
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]. |
Estimation methods and controlling the fit | |
n_starts |
1 |
Number of independent optimization runs. 1 disables multi-start (no behaviour change). |
Estimation methods and controlling the fit | |
nn_l2 |
float ≥ 0 | 0.0 |
L2 (weight-decay) strength. Adds nn_l2 · Σ wᵢ² over the network’s weight matrices only (bias terms are left free). |
Experimental features |
nn_smooth |
float ≥ 0 | 0.0 |
Smoothness (curvature) strength. Penalizes the finite-difference 2nd derivative C = f(x+h) − 2·f(x) + f(x−h) of each output along every input’s marginal partial-dependence curve, i.e. nn_smooth · Σ C². |
Experimental features |
npde_nsim |
integer ≥ 0 | 0 |
Number of Monte-Carlo replicates per subject used to compute the simulation-based NPDE/NPD diagnostics after the fit. | Diagnosing the model |
npde_seed |
integer | — | RNG seed for the NPDE/NPD simulation, for reproducible diagnostics. | Diagnosing the model |
ode_abstol |
float | 1e-6 |
RK45 ODE solver absolute tolerance (companion to ode_reltol). |
Structural models: analytical and ODE |
ode_auto_switch |
true, false |
true |
Let ode_method = auto change stepper inside an integration segment, not only at its start. |
Structural models: analytical and ODE |
ode_max_steps |
integer | 10000 |
Max solver steps per integration segment. ODE models and the absorption ODE twin. | Structural models: analytical and ODE |
ode_method |
auto, linear, rk45, vern7, rosenbrock23, rodas4, rodas5p |
auto |
Which stepper integrates the [odes] block — or, for a block that is linear in the states, whether to skip integration: auto solves such a model exactly by the matrix exponential, linear asserts that it must (a parse error naming the reason on a model that cannot), and naming any integrator opts out. |
Structural models: analytical and ODE |
ode_reltol |
float | 1e-4 |
RK45 ODE solver relative tolerance. Applies to ODE models, and to the auto-generated ODE twin that closed-form transit / inverse-Gaussian absorption models (one_cpt_transit, two_cpt_transit, one_cpt_ig, two_cpt_ig) use to serve IOV, time-varying-covariate, and TIME-switch subjects (#719/#814) — so a call-time override reaches those rerouted fits too; otherwise ignored for analytical PK. |
Structural models: analytical and ODE |
ode_stiff_abort_after |
integer ≥ 0, or off |
off |
Abandon an integration segment once this many of its steps have clamped at the minimum step size, instead of grinding on to ode_max_steps. |
Structural models: analytical and ODE |
omega_burnin |
20 |
Initial exploration iterations during which Ω (and ΩIOV) are held at their starting values while the MH chain warms up. | Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit |
optimizer_trace |
true, false |
false |
Write a per-iteration CSV to /tmp/ferx_trace_<pid>_<ts>.csv. |
Estimation methods and controlling the fit |
outer_ftol |
float | auto | Relative objective tolerance: the relative OFV change below which the optimizer stops. | Estimation methods and controlling the fit |
outer_xtol |
float | 1e-4 |
Relative step tolerance: how far the optimizer’s step must shrink before it declares success. | Estimation methods and controlling the fit |
parameter_scaling |
auto, none, abs, rescale2 |
auto |
Parameter-scaling strategy for the outer optimizer (supersedes scale_params when non-none). |
Variability: random effects, residual error and IOV |
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. | Estimation methods and controlling the fit |
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". |
Estimation methods and controlling the fit |
saem_imh_defensive |
0.05 |
Weight of the prior N(0, Ω) component mixed into the IMH proposal, in [0, 0.5]. |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
saem_imh_proposals |
2 |
Independent-MH proposals per subject per iteration under saem_kernel = imh. |
Estimation methods and controlling the fit | |
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). | Estimation methods and controlling the fit | |
saem_kernel |
rw |
The E-step’s primary kernel. rw is the block random walk. |
Estimation methods and controlling the fit | |
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). |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
scale_params |
false |
Legacy boolean alias for parameter_scaling = abs. Divide each packed (log/Cholesky) coordinate by its initial magnitude before passing it to the optimizer. |
Variability: random effects, residual error and IOV | |
seed |
12345 |
RNG seed for reproducibility | Estimation methods and controlling the fit | |
sir_df |
5.0 |
Degrees of freedom for the Student-t proposal (>= 1); higher values approach a normal proposal, and normal / mvn selects the multivariate-normal proposal itself (ν = ∞) |
Parameter uncertainty | |
sir_keep_samples |
false |
Retain resampled parameter vectors for simulate_with_uncertainty() |
Parameter uncertainty | |
sir_resamples |
250 |
Number of resampled vectors (m) | Parameter uncertainty | |
sir_samples |
1000 |
Number of proposal samples (M) | Parameter uncertainty | |
sir_scale |
packed |
Scale the SIR target is flat on: packed (log-sd for variances) or natural. |
Parameter uncertainty | |
sir_seed |
12345 |
RNG seed for reproducibility | Parameter uncertainty | |
stagnation_guard |
true |
Stop the NLopt-based outer optimizers early once the OFV stops improving; see below. | Estimation methods and controlling the fit | |
start_sigma |
0.3 |
Log-space perturbation applied to initial theta values for starts 1..n. | Estimation methods and controlling the fit | |
steihaug_max_iters |
integer | adaptive | Max CG iterations for the Steihaug subproblem (only used when optimizer = trust_region). |
Estimation methods and controlling the fit |
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. | Estimation methods and controlling the fit | |
vi_eta_grad |
auto |
auto uses the analytic Dual2 η-gradient where available and central finite differences where not; analytic and fd pin one route. |
Estimation methods and controlling the fit | |
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²). |
Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
vi_grad_clip |
1e4 |
Global-L2 gradient clip applied to every Adam step; 0 disables it. |
Estimation methods and controlling the fit | |
vi_iters |
25000 |
Adam ceiling, not a fixed budget — the run stops early once the objective and the estimates have both settled. | Estimation methods and controlling the fit | |
vi_kl |
analytic |
How the KL(q ‖ N(0, Ω)) half is evaluated — analytic in closed form (only the data term is sampled) or mc. |
Estimation methods and controlling the fit | |
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. | Estimation methods and controlling the fit | |
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. | Estimation methods and controlling the fit | |
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. |
Estimation methods and controlling the fit | |
vi_seed |
20240704 |
Seed for the common random numbers. See Reproducibility. | Estimation methods and controlling the fit | |
vi_sigma_update |
closed_form |
As vi_omega_update, for the residual error σ. See How σ is updated. |
Estimation methods and controlling the fit |
Model file blocks
The blocks a .ferx model file can contain. Required and Purpose are the ferx-core block overview at the pinned engine, and are blank for a block that overview does not list; the chapter column covers those. Block names are closed-world, so a header outside this table is an error.
| Block | Required | Purpose | Chapter | ferx-core page |
|---|---|---|---|---|
[adaptive_dosing] |
No | Feedback / TDM dose controller for simulate() |
Adaptive dosing and TDM strategies | adaptive-dosing |
[binary_model] |
No | Binary / logistic endpoint (needs --features survival) |
Binary endpoints | categorical |
[covariate_model] |
Covariate modeling | covariate-model | ||
[covariate_nn NAME] |
No | Neural-network covariate model (needs --features nn) |
Experimental features | covariate-nn |
[covariates] |
No | Declare which data columns are covariates (and how they interpolate) | Covariate modeling | covariates |
[data] |
No | Point at the dataset CSV; overridden by an explicit CLI/R path | Preparing and checking the analysis dataset | data |
[data_selection] |
No | Row/subject filters applied to the dataset | Preparing and checking the analysis dataset | data-selection |
[derived] |
No | Post-hoc derived quantities written to sdtab | Tables and figures | derived |
[diffusion] |
No | SDE diffusion terms | Experimental features | diffusion |
[error_model] |
Yes | Define the residual error model | Writing and managing model files | error-model |
[event_model] |
No | Time-to-event endpoint (needs --features survival) |
Time-to-event models | event-model |
[fit_options] |
No | Configure estimation method and optimizer | Writing and managing model files | fit-options |
[individual_parameters] |
Yes | Map population parameters to individual PK parameters | Writing and managing model files | individual-parameters |
[initial_conditions] |
No | Non-zero compartment initial amounts | Structural models: analytical and ODE | initial-conditions |
[markov_model] |
No | Continuous-time Markov endpoint (needs --features markov) |
Function, option and example index | markov-model |
[mixture] |
No | Mixture (subpopulation) model | Variability: random effects, residual error and IOV | mixture |
[odes] |
If ODE | ODE right-hand-side equations | Structural models: analytical and ODE | ode-models |
[output] |
No | Extra sdtab output columns | Tables and figures | output |
[parameters] |
Yes | Define theta, omega, and sigma parameters | Writing and managing model files | parameters |
[priors] |
Experimental features | priors | ||
[scaling] |
No | Compartment scaling / observation readouts | Structural models: analytical and ODE | scaling |
[simulation] |
No | Define a simulation trial design | Simulating scenarios | simulation |
[structural_model] |
Yes | Specify the PK model (analytical or ODE) | Writing and managing model files | structural-model |
Data columns
Columns the ferx data format recognises. Type and Meaning are taken from the ferx-core data format page at the pinned engine, and are blank for the columns that page does not list; the chapter column covers those.
| Column | Type | Meaning | Chapter |
|---|---|---|---|
ADDL |
Preparing and checking the analysis dataset | ||
AMT |
numeric | Dose amount (for EVID=1/EVID=4; also the dose-inference signal when EVID is absent) |
Preparing and checking the analysis dataset |
CENS |
integer | Censoring flag. 1 = below LLOQ and DV carries the LLOQ; -1 = above ULOQ and DV carries the ULOQ; 0 = quantified. |
Preparing and checking the analysis dataset |
CMT |
integer | Compartment number (1-indexed). Negative only on an EVID=2 row, where it turns that compartment off; see Compartment on/off. |
Preparing and checking the analysis dataset |
DV |
numeric | Dependent variable (observed concentration) | Preparing and checking the analysis dataset |
EVID |
integer | Event ID: 0 = observation, 1 = dose, 2 = other event, 3 = system reset, 4 = reset + dose. | Preparing and checking the analysis dataset |
FREMTYPE |
Covariate modeling | ||
ID |
string/numeric | Subject identifier | Preparing and checking the analysis dataset |
II |
numeric | Interdose interval for repeated dosing | Preparing and checking the analysis dataset |
MDV |
integer | Missing DV flag. 1 = DV should be ignored (row excluded from the likelihood). | Preparing and checking the analysis dataset |
RATE |
numeric | Infusion rate. 0 = bolus, >0 = constant-rate infusion (duration = AMT/RATE). |
Preparing and checking the analysis dataset |
SS |
integer | Steady-state flag. 1 = assume steady state | Preparing and checking the analysis dataset |
TENTRY |
Time-to-event models | ||
TIME |
numeric | Observation/event time on the data clock | Preparing and checking the analysis dataset |
Bundled examples
Every example is available with ferx_example() and its name, which returns the paths of its model and data (and $search for a search configuration).
Search configurations
| Example with $search | Chapter |
|---|---|
one_cpt_transit |
Model development and selection |
two_cpt_oral_base |
Model development and selection |
two_cpt_oral_cov |
Model development and selection |
two_cpt_oral_global |
Model development and selection |
warfarin |
Model development and selection |
warfarin_amd |
Model development and selection |
warfarin_block_omega |
Model development and selection |
warfarin_iov |
Model development and selection |
Warning categories
Categories of ferx_get_warnings(fit, as_df = TRUE)$category, collected by a fit that ran, with the severity and meaning ferx-core gives them at the pinned engine. Critical means the result is untrustworthy as it stands; Warning means it stands with a caveat; Info implies no action. A model that never ran fails with a check report code instead, listed under Check report codes below. Each chapter’s Warnings you may see here section covers the ones it meets, and the ferx-core warnings page describes them all.
| Category | Severity | Meaning | Chapter |
|---|---|---|---|
absorption_twin_declined |
Warning | An analytic transit / inverse-Gaussian model’s ODE twin could not be built, so the model keeps no ODE fallback (#1008). | Absorption and bioavailability |
bloq_method |
Warning | BLOQ / M3 censoring caveat. | Censored observations (BLOQ) |
boundary_estimate |
Warning | One or more THETA estimates are pinned to an optimizer bound. | Diagnosing the model |
cancelled |
Info | Run cancelled by the user. | Estimation methods and controlling the fit |
condition_number |
Critical | Ill-conditioned covariance / high condition number. The figure is only meaningful next to the estimator that produced it — read covariance_method from the details payload, or from the fit (Which covariance estimator produced these numbers). |
Diagnosing the model |
convergence |
Critical | Optimizer did not converge; or (W_NONFINITE_OBJECTIVE) the objective at the final estimates is NaN, infinite, or at or above the 1e14 divergence cutoff; or (W_NO_FEASIBLE_EVAL) not one outer trial was feasible — the EBE guard rejected them all, or every objective was non-finite — so nothing was minimised and the estimates are the ones the fit started from (#1617); or (W_ABOVE_START) the fit reported an objective materially above the one its starting estimates scored, restarts included, typically because the EBE guard rejected that first evaluation (#2461). |
Initial estimates and a first fit |
covariance_failed |
Critical | Covariance step failed — no standard errors. Every message that starts Covariance step failed gets this code, whatever reason it goes on to give (a message carrying a W_ token is classified by its token first): a profiled fit’s “the profile solve did not converge at the estimates” is a covariance failure, not convergence, and says nothing about whether the fit converged (#2158). |
Parameter uncertainty |
covariance_regularized |
Warning | Covariance step succeeded but an eigenvalue floor was applied, or an off-diagonal stencil was non-finite, or (W_COV_NON_STATIONARY_ESTIMATE, #1781) S⁻¹ replaced an r / rsr whose R needed an eigenvalue floor at a sampler’s estimate. |
Parameter uncertainty |
covariance_step |
Info / Warning | Covariance-step note (e.g. evaluation cost). W_COV_ODE_TOLERANCE_NOT_TIGHTENED (Warning): an integrated model’s covariance step, which finite-differences its R or S matrix, could not be run at ode_reltol = 1e-6 / ode_abstol = 1e-8 and ran at the fit’s looser tolerance, so the SEs may be inflated; pin those tolerances to compute them at the plateau (#520). |
Parameter uncertainty |
data_quality |
Warning | Dataset issue (missing DV, ADDL/II, non-positive DV, …). | Preparing and checking the analysis dataset |
degenerate_clearance_or_volume |
Warning | W_DEGENERATE_CL_V: the final estimates put a non-positive or non-finite CL or V on at least one dose, observation, EVID=2 or EVID=3/4 record of a 1-/2-/3-cpt IV / oral closed-form model, each record read under its own covariates and occasion κ (#2104); an EVID=4 row is one record, a separate EVID=3 row beside a dose is two. |
Covariate modeling |
dw_autocorrelation |
Warning | IWRES autocorrelation (Durbin–Watson out of range). | Diagnosing the model |
ebe_start_dependent |
Warning | (W_EBE_START_DEPENDENT) The empirical Bayes estimates at the final parameters depend on where the inner loop starts: re-solving them cold scores more than 0.05 OFV units worse than the EBEs the optimizer minimised against, or returns a non-finite objective (#833, #2646). |
Estimation methods and controlling the fit |
eps_shrinkage |
Warning | Residual (EPS) shrinkage high / negative. | Diagnosing the model |
eta_normality |
Warning | ETA departs from normality. | Diagnosing the model |
eta_shrinkage |
Warning | One or more ETA shrinkages exceed ~30%. | Diagnosing the model |
experimental |
Warning | An experimental feature (SDE, neural-network) was used. | Experimental features |
flat_parameter |
Warning | A non-fixed THETA has an ≈ 0 outer gradient at the initial estimate — it never reaches the objective (unmapped, or dropped from the structural / scaling model). | Estimation methods and controlling the fit |
flip_flop |
Warning | A transit / inverse-Gaussian absorption closed form entered the flip-flop regime (disposition rate ≥ the tilting abscissa). | Absorption and bioavailability |
general |
Warning | Unrecognised message (fallback bucket). | Initial estimates and a first fit |
gradient_fallback |
Info | A gradient / sampler fallback was taken. | Estimation methods and controlling the fit |
high_correlation |
Warning | One or more THETA (fixed-effect) pairs have |correlation| ≥ 0.95. | Diagnosing the model |
importance_sampling |
Warning | ESS = 0 / proposal collapse. | Estimation methods and controlling the fit |
inflated_rse |
Warning | One or more THETA estimates have RSE > ~50%. | Diagnosing the model |
init_not_representable |
Estimation methods and controlling the fit | ||
init_outside_bounds |
Warning | An initial estimate packs outside one of ferx’s internal rails (the hidden 1e9 THETA cap, the OMEGA ±6 / off-diagonal ±10 guards, the SIGMA [-8, 5] guard) and was clamped there before the first objective evaluation. |
Estimation methods and controlling the fit |
mu_referencing |
Warning / Info | Missing or partial mu-referencing. | Estimation methods and controlling the fit |
multi_start |
Info | Multi-start note. | Estimation methods and controlling the fit |
ode_rhs_route |
Structural models: analytical and ODE | ||
ode_solver |
Warning / Info | The ODE solver’s own health at the final estimates (#1080). Warning when steps clamped at the minimum step size (a stability-limited segment whose un-integrated tail is freeze-padded), when a segment stopped before its requested end, when ode_stiff_abort_after cut segments short, or when ode_method = auto discarded an escalation and re-solved it explicitly — including when only its analytic derivatives overflowed, its values staying finite — and when that re-solve failed too. |
Structural models: analytical and ODE |
omega_structure |
Warning | Mixed lognormal / additive block in omega. | Variability: random effects, residual error and IOV |
optimizer_config |
Warning / Info | global_search config note or failure. |
Estimation methods and controlling the fit |
optimizer_health |
Warning | Trust-radius collapse / degeneracy, or a fit that stopped mid-descent and was restarted from the best point it reached. | Estimation methods and controlling the fit |
parameter_at_runaway_guard |
Critical / Warning | A free coordinate is pinned to a hidden optimizer guard (implicit THETA cap, OMEGA / SIGMA rail), with a verdict the side does not decide. |
Estimation methods and controlling the fit |
simulation |
Warning | A simulated subject was handled specially — a degenerate hazard draw (censored, no event) or an over-large recurrent-event stream (skipped/truncated). | Time-to-event models |
sir |
Warning | SIR failed or was requested without a covariance; its proposal needed repair; or its effective sample size is below 100, naming the heaviest draw and any variance the data do not bound away from zero. | Parameter uncertainty |
stalled_at_init |
Warning | The fit never left its initial estimates — no free THETA, OMEGA or SIGMA coordinate moved, so the reported objective is the objective of the initial values. | Estimation methods and controlling the fit |
threads |
Info | Thread-count efficiency note. | Estimation methods and controlling the fit |
uncertainty_draws_skipped |
Warning | simulate_with_uncertainty_diag() skipped some parameter draws because they fell in the flip-flop regime of a twin-less transit / inverse-Gaussian closed form (#1485). |
Simulating scenarios |
vi_bad_basin |
Critical | VI’s final ELBO tightness check found that a flat objective is an unusable variational bound, not convergence. | Estimation methods and controlling the fit |
Check report codes
Stable identifiers from the model file parser and the pre-fit checks: E_* stops the model from running, W_* is a check-time note that does not. ferx_model_validate() returns them in $diagnostics, with the severity, block and line (Writing and managing model files). A refused call raises a condition of class ferx_engine_error – from ferx_fit(), ferx_predict(), ferx_simulate() and the other entry points alike – that carries the same identifier as $code, with $block, $line and $suggestion where the engine knows them (NA otherwise), and appends the code to the message in square brackets, so a script can branch on it with tryCatch(..., ferx_engine_error = function(e) e$code). These are a different channel from the Warning categories above, which a completed fit collects in fit$warnings. The 234 codes below (141 errors, 93 warnings) are the check report of the pinned engine, one sentence each; the ferx-core check report page gives the full text.
| Code | Severity | Meaning |
|---|---|---|
E_ABSORPTION_DIFFUSION |
error | An [odes] model whose right-hand side uses a built-in absorption input-rate function (transit(), igd(), weibull(), zero_order(), first_order()) also declares a [diffusion] block. |
E_ABSORPTION_DOMAIN |
error | A parameter of a built-in absorption input-rate function in [odes] is out of its domain at typical values (η = κ = 0), evaluated at every dose record’s own snapshot so a covariate or TIME-reading expression is caught at any dose: transit mtt ≤ 0 or n < 0, igd mat or cv2 ≤ 0, weibull td or beta ≤ 0, zero_order dur ≤ 0, first_order ka ≤ 0, or a non-finite per-route lag=. |
E_ABSORPTION_FRACTION |
error | A dose-splitting pathway fraction (FR*fn(...)) on a built-in absorption input-rate term is not in (0, 1], or the fractions on one compartment sum to something other than 1 (tolerance 1e-4), at typical values evaluated at each dose record. |
E_ABSORPTION_RATE_ZERO_ORDER |
error | A non-SS infusion (RATE > 0) into a compartment fed by a zero_order() absorption function in [odes]. |
E_ABSORPTION_SS_INFUSION |
error | A steady-state infusion (SS=1 with RATE > 0) into a compartment fed by a built-in absorption input-rate function in [odes]. |
E_ABSORPTION_SS_LAG |
error | An SS=1 dose with II > 0 into a compartment fed by a built-in absorption input-rate function, where that compartment has a lag time — a compartment lagtime / ALAG, or a per-route lag= on a forcing feeding it. |
E_ABSORPTION_SS_ZERO_ORDER |
error | An SS=1 dose with II > 0 into a compartment fed by a zero_order() absorption function in [odes]. |
E_AD_RETIRED |
error | gradient_method = ad was requested. The Enzyme automatic-differentiation path was retired; use auto (the analytic sensitivities, with finite differences outside their scope) or fd. |
E_ADAPTIVE_CONTROLLER_ACTION |
error | The controller returned an action the driver refuses (#1983): a dose into compartment 0 or one past the model’s states, an amount that is negative or not finite, an infusion rate that is not positive and finite, a dose into a compartment fed by a built-in input-rate function or carrying a lag, or a Stop followed by another action. |
E_ADAPTIVE_DOSE_KNOWLEDGE |
error | An [adaptive_dosing] dose expression reads a subject’s individual parameter or random effect, and some subjects’ η are drawn by the simulation, under dose_knowledge = known (the default) (#944). |
E_ADAPTIVE_DOSE_VALUE |
error | An [adaptive_dosing] dose expression whose value for one subject breaks a dose invariant (#944): not finite or negative, bounds with low > high, a start dose outside the bounds or not one of the levels, a rung outside the bounds, a ladder that does not increase, no multiple of round_to within the bounds, or a low bound of 0 with round_to under percentage steps. |
E_ADAPTIVE_OPTIONS |
error | AdaptiveSimulateOptions with no usable schedule (decision_times empty, not finite, not strictly increasing, or longer than max_decisions), a monitor on a compartment the model does not have, a Dv monitor on a compartment no [error_model] covers, or decision_times / monitors set alongside an [adaptive_dosing] spec that owns them. |
E_ADAPTIVE_SPEC |
error | An [adaptive_dosing] spec that does not compile against the model: an invariant the block parser checks (on a spec built in code), an assay_cmt out of range or with no [error_model] to draw the assay from, a route compartment out of range or fed by a built-in input-rate function, or an observe expression that does not compile. |
E_ADAPTIVE_UNSUPPORTED |
error | A model the adaptive-dosing driver cannot simulate faithfully (no [odes] block, an SDE, a covariate-selected [error_model], a residual correlation line, a log-transformed (LTBS) error model — #2129), refused before any subject is simulated. |
E_AGQ_EVAL_ONLY |
error | agq_eval_only = true turns a laplace stage into a likelihood evaluator, so it needs a laplace stage in the chain and that stage must be the last one. |
E_AGQ_GRID_TOO_LARGE |
error | A quadrature stage — method = laplace, or method = focei with n_agq > 1 — whose tensor grid of n_agq^n_eta nodes per subject exceeds MAX_AGQ_GRID (100,000). |
E_AGQ_NODES_TOO_LARGE |
error | A quadrature stage — method = laplace, or method = focei with n_agq > 1 — with n_agq above MAX_AGQ_NODES (21), where the Golub–Welsch rule loses accuracy. |
E_AGQ_NODES_ZERO |
error | n_agq = 0, under any method. Zero nodes must not silently disable FOCEI quadrature or be coerced to one-node Laplace, and a method that ignores n_agq still records it in the fit, where a .fitrx holding 0 does not load (#1770); use n_agq = 1. |
E_BINARY_GN_UNSUPPORTED |
error | gn or gn_hybrid anywhere in the method chain on a model with a [binary_model] (binary or categorical) endpoint. |
E_BINARY_STATE |
error | A [binary_model] record whose DV is not 0 or 1. The reader accepts any non-negative integer on a discrete compartment, since it cannot tell binary from ordinal. |
E_BLOCK_FEATURE_DISABLED |
error | A recognised block needs a cargo feature this binary was not built with — [event_model] / [binary_model] need --features survival, [markov_model] needs --features markov. |
E_BLOCK_INSTANCE_NAME |
error | A [block NAME] instance name is given for a block that takes none (e.g. [fit_options DOSE]), or omitted for one that requires it ([covariate_nn NAME]). |
E_BLOCK_SIGMA_CHAIN_UNSUPPORTED |
error | A block_sigma model with at least one free (non-FIX) correlation, whose method chain places a stage that cannot read the estimated correlation (anything but foce, focei, laplace) after a stage that estimates it. |
E_BLOCK_SIGMA_FREM_UNSUPPORTED |
error | A block_sigma (correlated residual error) model that is also a FREM model with covariate pseudo-observations; the combination is not supported. |
E_BLOCK_SIGMA_IOV_UNSUPPORTED |
error | A block_sigma (correlated residual error) model with inter-occasion variability (n_kappa > 0) fitted by a method other than foce / focei, or with n_agq > 1. |
E_BLOCK_SIGMA_METHOD_UNSUPPORTED |
error | A block_sigma (correlated residual error) model whose method chain contains a stage outside foce, focei, saem, imp, laplace and vi — that is, gn, gn_hybrid, impmap or bayes. |
E_BLOCK_SIGMA_SDE_UNSUPPORTED |
error | A block_sigma (correlated residual error) model with a [diffusion] block and a saem stage in the method chain. |
E_BLOCK_SIGMA_TTE_UNSUPPORTED |
error | A block_sigma (correlated residual error) model that also declares a non-Gaussian endpoint ([event_model], [binary_model] or [markov_model]), whatever the method. |
E_BLOCK_VARIANCE_ONLY |
error | A scale tag ((sd), (variance) or (var)) on a block_omega, block_sigma or block_kappa declaration. |
E_CMT_TOGGLE_OUT_OF_RANGE |
error | A CMT=-N off row past the [odes] block’s declared states (#2732). See Compartment on/off. |
E_CMT_TOGGLE_SS |
error | An SS=1 dose while a compartment is off (#2732). See Compartment on/off. |
E_CMT_TOGGLE_TIE |
error | A compartment on/off row between two doses, or a reset and a dose, at one TIME: no engine order can place it (#2732). |
E_CMT_TOGGLE_UNSUPPORTED |
error | A compartment off row (EVID=2, CMT=-N) on a model that cannot honour it: not an [odes] model, an SDE, a declared endpoint, or a compartment fed by a built-in absorption input (#2732). |
E_COV_LEVEL_UNKNOWN |
error | The data carry a value of a categorical [covariate_model] covariate that is not one of the relation’s levels, which the generated factor would silently model as the reference level (#1111, #1740). |
E_COVARIATE_NOT_NUMERIC |
error | A column the [covariates] block declares holds a value that is not a number. Block covariates. |
E_COVARIATE_STATS_BINDING |
error | A [covariate_model] statistic could not be bound to the data: a levels = auto relation whose data carry one level, or a covariate with no non-missing value. |
E_COVSTAT_UNRESOLVED |
error | A [covariate_model] relation still needs statistics derived from the data — center = median, levels = auto, or a form whose default bounds come from the data — and none were bound. |
E_CTMM_GN_UNSUPPORTED |
error | gn or gn_hybrid anywhere in the method chain on a model with a [markov_model] (CTMM) endpoint. |
E_CTMM_IOV_UNSUPPORTED |
error | A [markov_model] (CTMM) endpoint on a model with inter-occasion variability (n_kappa > 0), whatever the method. |
E_CTMM_RECORDS |
error | A [markov_model] (CTMM) record whose DV is not one of the declared states, or a subject whose CTMM observation times decrease (the reader sorts doses, not observations). |
E_CTMM_UNSUPPORTED |
error | A [markov_model] endpoint reached predict() with no continuous observation to predict, or simulate() or run_model_simulate(): neither has a state-occupancy path yet (#820). |
E_DATA |
error | The --data file could not be read or parsed. |
E_DATA_PATH_MISSING |
error | No data path was given and the model file has no [data] block. ferx check without --data skips its data checks instead of refusing. |
E_DEPRECATED_BLOCK |
error | A [block] that was ferx syntax and is no longer read — currently [initial_values], whose contents moved inline into [parameters]. |
E_DERIVED_NAME_CONFLICT |
error | A [derived] name clashes with a built-in sdtab column, theta, eta, or individual-parameter name. |
E_DOSE_ATTR_DOUBLE_USE |
error | A dose attribute the engine applies at the dose event is also read by the model, so its value is applied twice. |
E_DOSE_ATTR_NONFINITE |
error | A dose attribute the engine applies at the dose event — lag time (lagtime / ALAG{n}), bioavailability (F / F{n}), or a modeled infusion duration D{n} / rate R{n} behind a coded RATE — is NaN or infinite at typical values for some subject. |
E_DOSE_CMT_NOT_INFUSABLE |
error | Raised on [odes] models and the event-walk analytical models (not transit / inverse-Gaussian); reported once per compartment, with the subject and time of the first row. |
E_DOSE_CMT_OUT_OF_RANGE |
error | A dose record — bolus or infusion, zero amount included — whose CMT exceeds the number of compartments: the [odes] block’s declared states, or the analytical model’s compartments. |
E_DOSE_NO_AMT |
error | The dataset has dose records (EVID 1 or 4) but no AMT column, so every dose would have amount zero and the fit would run with no drug in the system. |
E_ENDPOINT_NO_RECORDS |
error | A declared non-Gaussian endpoint has no row routed to it anywhere in the data — typically the CMT column is missing, so every row reads as CMT 1. |
E_ENDPOINT_TIME_DEPENDENT_PK |
error | The TIME axis of the same freeze: an ODE-accumulated (drug-driven) hazard integrates the individual parameters at their TIME=0 values, so a [individual_parameters] value that reads TIME and reaches the hazard (through the [odes] right-hand side or an init() seed) would put the PK and hazard halves of the objective on different concentration curves (#1853). |
E_ENDPOINT_TV_COVARIATE |
error | A covariate that varies within a subject — on any row, endpoint rows included (#1854) — is read by an endpoint that evaluates it once, at the subject’s baseline: an analytic hazard’s own parameters, any covariate under an ODE-accumulated (drug-driven) hazard, a [markov_model] CTMM transition intensity, or — on a drug-driven (time-inhomogeneous) CTMM — an individual parameter the [odes] solve feeds into the states the intensities read (#1854). |
E_ENDPOINT_UNROUTED |
error | A compartment the model declares as a non-Gaussian endpoint ([event_model], [binary_model], Markov) carries Gaussian observations: the population was read without endpoint routing, so the endpoint’s rows would be scored as concentrations and its likelihood would contribute nothing. |
E_ETA_NOT_DECLARED |
error | An unresolved identifier reads as a random effect (ETA… / KAPPA…) but no omega / kappa declaration defines it, and the data carries no such column. |
E_FIT_INPUT_CHANGED |
error | The model or data file the step re-reads no longer has the SHA-256 the fit recorded. |
E_FIT_INPUT_MISSING |
error | An input the step needs was neither passed nor recorded on the fit: the model file’s path (no model passed), the data file’s path (no population passed), SIR’s covariance matrix, the population of an IOV model passed as a model on a fit that records no reader settings, the occasion rule of an IOV fit saved before ferx recorded one, on a population that carries no occasion labels, or the fitted values of a [mixture] fit’s per-class overrides, on a fit that records neither them (mixture_overrides) nor a packed estimate holding them. |
E_FIT_INPUT_MODEL |
error | The model the step would run on is not the one the fit was made with: a model passed in bound with other data-derived bindings than the fit’s, a model passed in whose covariate statistics the population does not reproduce (on a fit that records no bindings), a model whose η count is not the width of the fit’s per-subject η̂, a [mixture] fit whose recorded override values are malformed, or which records none and whose packed estimate has another layout or no longer reproduces its reported estimates, or a covariance matrix that is not the size of the model’s packed parameters. |
E_FIT_OPTION |
error | A call-time fit-option override handed to validate_model_file_with() could not be applied: the key is not a [fit_options] / [data_selection] key, or its value is one the key does not accept. |
E_FIT_SUBJECTS_MISMATCH |
error | The population matches the fit’s fingerprint, but the fit’s per-subject results (fit.subjects), which run_sir / run_covariance read by position, are another count or another order (#1868). |
E_FOCEI_NAGQ_UNSUPPORTED |
error | method = focei with n_agq > 1 (the Gauss-Newton-anchored quadrature) on a model outside the analytic sensitivity scope, e.g. an ODE model without sensitivities or a pure TTE endpoint. |
E_FREM_NON_GAUSSIAN_ENDPOINT |
error | prepare_frem() or transform_dataset_for_frem() was handed a model that declares a non-Gaussian endpoint ([event_model], [binary_model] or [markov_model]). |
E_IG_FLIP_FLOP |
error | An inverse-Gaussian absorption model (one_cpt_ig / two_cpt_ig) with no ODE twin to reroute to whose typical-value (η = 0) parameters fall outside the closed form’s convergence domain on some subject — the flip-flop regime (disposition rate ≥ 1/(2·MAT·CV²)) or, for 2-cpt, coincident disposition eigenvalues — where it returns an identically-zero profile. |
E_IG_UNSUPPORTED |
error | An inverse-Gaussian absorption model (one_cpt_ig / two_cpt_ig) with a dose or model feature its closed form cannot serve. |
E_IIV_ON_RUV_METHOD |
error | iiv_on_ruv with a non-interaction stage (foce, or gn without interaction) anywhere in the method chain. |
E_IIV_ON_RUV_SHARED_ETA |
error | The iiv_on_ruv random effect is also used in [individual_parameters]. It must be a dedicated omega. |
E_IMP_CHAIN |
error | imp is mis-placed in a method chain — repeated, or (with imp_eval_only = true) not the terminal stage. |
E_IMP_MIXTURE_IOV_UNSUPPORTED |
error | imp or impmap anywhere in the method chain on a [mixture] model with inter-occasion variability (n_kappa > 0). |
E_INIT_BOUNDS_INVERTED |
error | A coordinate whose packed box is empty, so no start can be placed in it at all. |
E_IOV_MISSING_OCC |
error | Model declares kappa (IOV) parameters but no occasion labels were found. Set iov_column to read them from a dataset column, or iov_occasion = dose / time(...) to derive them in the model, both in [fit_options]. |
E_IOV_SINGLE_OCCASION |
error | A derived iov_occasion rule (dose or time(...)) gives every subject at most one occasion, so the per-occasion κ cannot be told from the η. |
E_KAPPA_WEIGHT_NONPOSITIVE |
error | A kappa NAME ~ value weight = W sample-size weight evaluates to zero, a negative number or a non-finite value at some observation or dose record, at the model’s initial θ. κ is applied as κ/√W, so such a weight divides an individual parameter by zero. |
E_LEVEL_MISSING_LABEL |
error | A record (observation, dose, EVID=2 / MDV=1 row or reset) has no numeric value in a level column (a blank cell is missing, not carried forward from the row before; a text label such as NCT01 has to be written as a numeric code). |
E_LEVEL_MIXED_WITH_IOV_COLUMN |
error | A level declaration together with iov_column or iov_occasion in [fit_options], an iov_occasion rule other than column in the fit options or SimulateOptions of a model with nested levels (block fit_options), or a kappa with no at LEVEL in a model that declares levels. |
E_LEVEL_SINGLE_MEMBER |
error | A level has at most one group inside every group of its parent, and one of its kappas enters the model through the same parameters as a random effect of the parent level (the subject’s η for the first level). |
E_LOGIT_THETA_OUT_OF_RANGE |
error | A free θ used as inv_logit(logit(θ) + ETA) whose estimate is not strictly inside (0, 1), so it has no logit-scale draw (#2044). |
E_LTBS_UNSUPPORTED |
error | LTBS (log_transform = true) with a proportional or (natural-scale) combined error on any endpoint, a covariate-selected error model, or an SDE; or a LogCombined error without LTBS. |
E_METHOD_NO_RANDOM_EFFECTS |
error | method = imp, impmap or bayes (anywhere in a method chain) on a model with no random effects (n_eta = 0). |
E_MISSING_BLOCK |
error | A required [block] is absent. block names which one. |
E_MISSING_COVARIATE |
error | The model references a covariate not present in the data (case-sensitive). On block covariates, a column the [covariates] block declares is missing from the file. |
E_MIXTURE_METHOD |
error | A [mixture] model with a method its objective is not wired for: method = focei with n_agq > 1, an estimator other than foce / focei / saem / bayes / imp / impmap, or bayes with per-class omega(k) / sigma(k) overrides, since its Ω draw is shared across classes. |
E_MODEL_READ |
error | The model file could not be read: it does not exist, cannot be opened, or is not UTF-8. |
E_MODELED_DURATION_NO_PARAM |
error | A dose codes RATE=-2 (modeled infusion duration) into compartment n, but the model declares no D{n} in [individual_parameters], so the duration has no value to read. |
E_MODELED_RATE_NO_PARAM |
error | A dose codes RATE=-1 (modeled infusion rate) into compartment n, but the model declares no R{n} in [individual_parameters], so the rate has no value to read. |
E_NEGATIVE_CMT |
error | See Compartment on/off. |
E_NEGATIVE_LAGTIME |
error | A dose lag — lagtime / ALAG{n}, or a per-route fn(..., lag=L) on the compartment the dose lands in — is negative at the initial typical-value point (η = 0), at some dose record’s own snapshot. |
E_NESTED_LEVEL_METHOD_UNSUPPORTED |
error | A model with nested levels (more than one level) fitted with a method other than foce / focei at n_agq = 1: SAEM, IMP, IMPMAP, Bayes, VI, Laplace, FOCEI quadrature or GN anywhere in the chain, or with a [mixture] or FREM. |
E_NESTED_LEVEL_SIMULATE_UNSUPPORTED |
error | A model with nested levels (more than one level) reached an adaptive-dosing entry point. |
E_NN_FEATURE_DISABLED |
error | A [covariate_nn] block requires building with --features nn. |
E_NO_SCORED_OBSERVATIONS |
error | The population has no record the likelihood scores: no Gaussian observation and no endpoint (TTE / binary / categorical / Markov) record on any subject. |
E_NONFINITE_DV |
error | A subject carries a non-finite (NaN/Inf) observation. Usually a population read by read_population_for_simulation() — a simulation input — passed to fit(). |
E_OBS_CMT_OFF |
error | See Compartment on/off. |
E_ODE_METHOD_LINEAR |
error | ode_method = linear was passed in a caller’s fit options (fit(), run_covariance, run_sir) for a model that cannot take the exact linear path: it has no [odes] block, or an equation is nonlinear in the states, reads model time, or uses an absorption input function, or it is a [diffusion] model. |
E_ODE_SOLVER_OPTIONS |
error | ODE solver settings on a FitOptions built in code that no solver can run with: an ode_reltol or ode_abstol that is not finite and positive, ode_max_steps = 0 (#2044), or ode_stiff_abort_after = Some(0), which [fit_options] spells as off (#1770). |
E_OMEGA_INIT_AT_RAIL |
error | A free omega / kappa / [mixture] omega(k) variance whose initial value packs onto the optimizer’s -6 lower rail — every variance ≤ 6.1e-6, and ~ 0.0 in particular (a declared zero is regularised to 1e-8, packing to ln(L) = -9.21). |
E_OPTIMIZER_AGQ |
error | optimizer = trust_region used with a quadrature stage (method = laplace, or method = focei with n_agq > 1). |
E_OPTIMIZER_IOV |
error | optimizer = trust_region used with an IOV model (n_kappa > 0). |
E_OUTPUT_UNKNOWN_COLUMN |
error | A name in [output] is not recognised as a covariate, individual parameter, or derived expression. |
E_PARAM_SHAPE |
error | An entry point was handed an Ω, σ or ΩIOV whose dimension is not the model’s, an ΩIOV on a model with no κ, or none on a model with κ, and refused it rather than read it by position (#1764, #1774). |
E_PARSE |
error | The model file failed to parse (catch-all for parser errors). |
E_PER_CMT_ERROR_MODEL |
error | An observed compartment lacks a per-CMT [error_model] entry. |
E_PER_CMT_SCALING |
error | An observed compartment lacks a per-CMT scaling entry. |
E_POPULATION_MISMATCH |
error | A population handed to, or re-read by, a post-hoc step is not the one the fit was given (#1685): another subject list, other covariate columns, or a subject whose records, doses or covariate values differ. |
E_PRIOR_COV_METHOD_UNSUPPORTED |
error | A prior(...) is in force and the covariance step runs with covariance_method = s or rsr. |
E_PRIOR_METHOD_UNSUPPORTED |
error | A prior(...) is in force but the last stage that estimates (a trailing evaluation-only imp or laplace does not count) is not one that applies parameter priors — only foce, focei, laplace, gn and gn_hybrid do. |
E_PRIOR_UNRESOLVED |
error | A declared prior cannot be applied: it names no theta / omega / sigma / kappa in [parameters], names a FIXed parameter, an element of a block_omega / block_sigma / block_kappa, or a name that resolves to several coordinates; it is declared twice; its central value is not finite (or not positive for a log-packed parameter); or a [priors] from_fit was not expanded. |
E_PROFILE_NOT_LINEAR |
error | A profiled block that a prediction does not read as c × block plus terms that do not read it, with c from the data alone, or as one logit link around such a read that is the whole prediction (y = inv_logit(c × block + …), #2111). |
E_PROFILE_SCOPE |
error | A profiled block that cannot be fitted that way: profile on a single θ, or with FIX; a box that is a point, is empty or misses the init; a method other than foce / focei / laplace (at any n_agq); a time-to-event or Markov endpoint (a binary one is in scope, #2111); a residual error that is not additive, or log-transformed; M3 censoring; a [mixture], [diffusion] or FREM model; optimizer = trust_region or mma; global_search; a parameter prior. |
E_PROPENSITY_INPUT |
error | Propensity-score matching was requested on a population it cannot compute posthoc etas from: empty, a subject with no observations, a subject with a non-finite DV, or a [mixture] model. |
E_READOUT_DEPOT_UNSUPPORTED |
error | An analytic [scaling] y = … readout reads the oral depot amount on a subject whose depot dose superposition cannot reconstruct: one with an EVID=3/4 reset (#650), or one dosing a compartment other than the default (#375). |
E_RESIDUAL_CORRELATION_CONFOUNDED_KAPPA |
error | A correlation cs(…) by … line whose blocks group the observation rows exactly as the groups of a level that carries a kappa (a nested level, or the occasions of a one-level model), compared as partitions in every subject, so cs by ARMID beside kappa … at ARM counts. |
E_RESIDUAL_CORRELATION_GROUPING_AMBIGUOUS |
error | A residual correlation … by line on a model with nested levels whose grouping a level and a data column would read two ways: a level name inside a list of columns (by (STUDY, ARM)), a level name that is also a different data column, or the by column of a level nested in another level written under another name. |
E_RESIDUAL_CORRELATION_RANGE |
error | The θ behind a residual correlation <kind>(RHO) by … line can leave the residual covariance R indefinite: a cs ρ at or below −1/(n−1) for the largest block of n rows, a negative car1 ρ, or a fixed / simulated value with abs(ρ) ≥ 1. |
E_RESIDUAL_CORRELATION_RESET |
error | Under a residual correlation ar1(…) or car1(…) line, one block holds rows on both sides of a TIME reset (an EVID=3/4 record that restarts TIME), so their order and the lag between them are undefined. |
E_RESIDUAL_CORRELATION_SCOPE |
error | A residual correlation line is fitted by foce and focei only. Refused with any other method anywhere in the chain, with n_agq > 1, with bloq_method = m3, with FREM covariate pseudo-observations, with a time-to-event / binary / categorical / Markov endpoint, with a mixture model, or with an SDE ([diffusion]) model. |
E_RESIDUAL_CORRELATION_TIES |
error | Under a residual correlation ar1(…) or car1(…) line, two rows of one block share a TIME. |
E_RTTE_RECORDS |
error | A repeated-event (type = rtte) endpoint’s records: interval-censored, a non-finite TIME, an entry time after the record’s TIME, or out of time order; under clock = reset also a right-censored row before a later record, or two events at one TIME. |
E_RUV_MAGNITUDE_NONPOSITIVE |
error | A custom residual-error magnitude in [error_model] — an expression multiplying a sigma, such as a weight = ... modifier — or a power(SIGMA, P) exponent evaluates to zero, a negative number or a non-finite value at some observation, at the model’s initial θ. |
E_SAEM_NO_RANDOM_EFFECTS |
error | method = saem (anywhere in a method chain) on a model with no random effects (n_eta = 0). |
E_SDE_INCOMPATIBLE |
error | An SDE ([diffusion]) model used with an incompatible method (saem, gn, gn_hybrid) or gradient setting. |
E_SIGMA_ORDER_MISMATCH |
error | A single-endpoint [error_model] names its sigmas in an order other than the [parameters] declaration order. |
E_SIMULATE_HORIZON |
error | The simulation horizon is missing where a repeated-event or drug-driven TTE endpoint needs one (on an entry point that takes a horizon), is not finite and positive, or lies below a subject’s entry time. |
E_SIMULATION_DESIGN |
error | A [simulation] design that gives the model nothing to observe: no times for a continuous (residual-error) or [binary_model] endpoint, or no times and no TTE endpoint to observe at a horizon. |
E_SIR_NOTHING_TO_SAMPLE |
error | every estimated parameter of the fit is FIX (θ, Ω and σ, and Ω_IOV, block_sigma correlations and [mixture] overrides where the model has them), so run_sir() has nothing to sample. |
E_SIR_OPTIONS |
error | SIR settings run_sir() cannot run with: sir_resamples above sir_samples, a sir_df that is not a valid Student-t degrees of freedom, or sir_scale = natural on a model with prior(...). |
E_SUPPLIED_ETAS |
error | Per-subject η supplied to an adaptive run, or to predict_survival_at_etas_diag, that cannot be used as given (#1594, #1885). |
E_THETA_GATHER_INDEX_MISSING |
error | A theta NAME[...] block gathered by a bare data column, where some observation or dose record of a subject has no value in that column. |
E_THETA_GATHER_INDEX_RANGE |
error | A theta NAME[...] block’s index column holds a value on some record that is not finite, not a whole number, or outside 1..=N for the block’s N levels. |
E_THETA_INIT_OUTSIDE_BOUNDS |
error | A theta whose initial value is strictly outside its own declared range. The optimizer clamps the start into its box, so theta TVCL(0.05, 0.1, 10.0) fits from 0.1 — a factor of two — silently, on every run. |
E_THETA_LENGTH |
error | An entry point taking a parameter vector was handed a θ whose length is not the model’s, and refused it rather than read it by position. |
E_THETA_LEVEL_BINDING |
error | A theta NAME[COL, ...] level block could not be bound to the data’s levels: a level column missing or non-finite, no row that defines a level (no observation rows, or on data with only binary, Markov, time-to-event or count records, no endpoint that reads the block bare through its implicit index and whose records define levels), or a contrast the data cannot carry. |
E_THETA_LEVELS_DATA_MISMATCH |
error | A population that carries a bound level block’s index was bound for other levels than the model’s (#1762): a record’s index is not the position, in the model’s level table, of the label its own level columns spell, or an index arrives without its level column. |
E_THETA_LEVELS_DATA_UNBOUND |
error | A model whose theta NAME[...] level block is bound was handed a population never bound for it, so no record carries an index into the block’s levels — the usual “fit, then predict or simulate new data” without binding the new data. |
E_THETA_LEVELS_UNBOUND |
error | A theta NAME[...] level block was never bound to data, so it has no levels and every value gathered from it is NaN — a CompiledModel assembled in code that skipped the binder. |
E_TRANSIT_FLIP_FLOP |
error | A transit absorption model (one_cpt_transit / two_cpt_transit) with no ODE twin to reroute to whose typical-value (η = 0) parameters fall outside the closed form’s convergence domain on some subject — the flip-flop regime (disposition rate ≥ KTR = (n+1)/mtt) or, for 2-cpt, coincident disposition eigenvalues — where it returns an identically-zero profile. |
E_TRANSIT_UNSUPPORTED |
error | A transit absorption model (one_cpt_transit / two_cpt_transit) with a dose or model feature its closed form cannot serve. |
E_TTE_NOT_SIMULATABLE |
error | A TTE endpoint the event-time simulator cannot draw for this population: more than one repeated-event stream on a subject, a repeated-event cause beside a single-event one, an EVID=3/4 reset under a repeated-event or a drug-driven hazard, or left truncation under a drug-driven hazard. |
E_UNKNOWN_BLOCK |
error | A [block] header is not a recognised block name. The message lists every offending header with its line, the valid set this build accepts, and a did-you-mean when there is a near match; suggestion carries the near match on its own. |
E_VI_MODEL_UNSUPPORTED |
error | method = vi (anywhere in a method chain) on a model whose likelihood VI’s data term — the fixed-η Gaussian observation NLL — does not cover: one with a non-Gaussian endpoint (time-to-event, binary, categorical; under the survival feature), or an SDE ([diffusion]) model scored by the EKF. |
E_VI_NAGQ_UNSUPPORTED |
error | n_agq > 1 set on a method chain that contains vi and no stage that uses a quadrature grid (laplace or focei). |
E_VPC_TTE_INPUT |
error | An input the Kaplan–Meier VPC (vpc_tte()) would draw a wrong curve or band from: several TTE endpoints and no cmt, a cmt that is not a TTE endpoint, a repeated-events endpoint, left truncation, an interval-censored record, more than one record per subject on the endpoint, a duplicated subject id, no record on the endpoint, band probabilities not strictly inside (0, 1) and increasing, too few replicates for them, a grid time that is not finite and non-negative, or a stratification covariate a subject lacks or with more than 10 values (#1886). |
W_ABOVE_START |
warning | The fit reported an objective materially above (the plateau check’s relative \(10^{-3}\) bound) the one its starting estimates scored — after any restart, which is measured against the fit’s start, not its own, so the fit is converged: false. |
W_ABSORPTION_TWIN_DECLINED |
warning | An analytic transit / inverse-Gaussian model’s ODE twin could not be built, so the model stays closed-form with no ODE fallback. |
W_ADAPTIVE_DECISION_BEFORE_MOVED_RESET |
warning | An adaptive simulation has a decision point after an EVID=3/4 reset as written, but before that reset on the engine clock. |
W_ADAPTIVE_DOSE_ORACLE |
warning | Under dose_knowledge = oracle, some subjects of an adaptive simulation were dosed from their drawn individual parameters or random effects (#944): a perfect-information comparison arm, since no prescriber has these values. |
W_ADDITIVE_INIT_SCALE |
warning | A combined error model’s additive SD initial estimate is below 1% of the data scale (the median abs(DV) of the observations that endpoint covers). |
W_ADDL_MISSING_II |
warning | ADDL > 0 on a dose row but II is zero or missing; additional doses were not expanded. |
W_ALL_DOSES_ZERO |
warning | An AMT column is present and at least one dose event was parsed, but every parsed amount is exactly zero. |
W_AMT_NOT_DOSED |
warning | Record(s) carry AMT != 0 but were not read as dose events, because EVID is neither 1 nor 4; their AMT was ignored. |
W_AUTO_OPTIMIZER_FOLLOWS_GRADIENT |
warning | gradient = fd set while optimizer is left at auto, on a model whose analytic outer gradient is in scope. |
W_CENS_UNEXPECTED |
warning | An observation row’s CENS cell is a whole number other than -1 (above ULOQ), 0 (quantified) or 1 (below LLOQ), such as 7 or -2. |
W_CMT_DEFAULTED |
warning | Dose and observation rows were assigned compartment 1 because the dataset did not say which one — no CMT column, or a cell that is missing (./blank/NA) or not a compartment index. |
W_COMPARTMENT_FREE_DOSES |
warning | The dataset carries dose records but the [structural_model] is compartment-free, so no dose is applied and AMT / RATE / SS / CMT on those rows have no effect on the prediction. |
W_COV_ANALYTIC_SALVAGE |
warning | The covariance step assembled the exact analytic R matrix for the subjects inside the analytic scope and finite-differenced the information terms of the subjects outside it, rather than moving the whole population onto the finite-difference stencil (#1514). |
W_COV_NN_PENALTY |
warning | A regularized [covariate_nn] fit (nn_l2 / nn_smooth): under covariance_method = r / rsr the standard errors include the penalty’s curvature (penalized-ML SEs, Info); under s they cannot represent it (Warning) (#1352). |
W_COV_NON_STATIONARY_ESTIMATE |
warning | The covariance R matrix needed an eigenvalue floor (indefinite, or an eigenvalue under max(1e-10·λ_max, 1e-12)) at a saem / imp / impmap / vi estimate, which those methods never minimise the R objective at. |
W_COV_ODE_TOLERANCE_NOT_TIGHTENED |
warning | An integrated model’s covariance step, which finite-differences its R stencil or score matrix S, could not be run at ode_reltol = 1e-6 / ode_abstol = 1e-8 and ran at the fit’s looser tolerance, so the standard errors may be inflated by integration noise (#520). |
W_COV_PROFILED_LEVELS_RESOLVED |
warning | run_covariance on a profiled fit whose level estimates are not the profile solve’s at the other estimates, because they were edited after the fit. |
W_COV_QUADRATURE_DECLINED |
warning | The same kind of fit, where the quadrature marginal could not be used — a mixture, inter-occasion variability, or more than three random effects — so the standard errors are the FOCEI objective’s curvature at a point that objective need not minimise (#1781). |
W_COV_QUADRATURE_OBJECTIVE |
warning | A saem / imp / impmap estimate on a model with a non-Gaussian endpoint had its covariance R and S matrices taken on the 7-node adaptive Gauss–Hermite marginal (method = laplace, n_agq = 7) rather than on the FOCEI objective, whose minimum can sit far from that estimate (#1781). |
W_COV_RSR_ONE_SUBJECT_LEVELS |
warning | A successful covariance_method = rsr step on a model with a θ level block, profiled or not, where some estimated levels are read by a single subject (an MBMA block over [STUDY, TIME] with one subject per study). |
W_COVARIATE_MISSING |
warning | A covariate column that exists has no value (every cell ., blank or NA) for some subjects, so it is NaN for them. |
W_COVSTAT_UNBOUND |
warning | As E_COVSTAT_UNRESOLVED, but reported without a --data file: the model is fine, it just cannot be built until a dataset supplies the statistics. |
W_DATA |
warning | A warning from the data reader whose message does not begin with its own W_ code. |
W_DATA_PATH_OVERRIDE |
warning | A data path was passed explicitly (--data, or from R) and the model file’s [data] block names a different file — compared as written, then as canonicalized paths. |
W_DEGENERATE_CL_V |
warning | The final estimates put a non-positive or non-finite CL or V on at least one dose, observation, EVID=2 or EVID=3/4 record of a 1-/2-/3-cpt IV / oral closed-form model, each record read under its own covariates and occasion. |
W_DERIVED_CMT_IOV_UNSUPPORTED |
warning | A [derived] expression reads compartments[i], and at least one subject of the fit carries IOV (kappa) parameters. |
W_DERIVED_CMT_ORAL_DEPOT_INFUSION_ANALYTICAL |
warning | A [derived] expression reads compartments[i] on an analytical (non-[odes]) model where some subject has a dose the closed-form superposition cannot place: an infusion into a compartment other than central (including a zero-order input into the oral depot) or a bolus into a compartment other than 1. |
W_DERIVED_CMT_RESET_ANALYTICAL |
warning | A [derived] expression reads compartments[i] on an analytical (non-[odes]) model where some subject has an EVID=3/4 reset. |
W_DERIVED_CMT_TV_ANALYTICAL |
warning | The model has no [odes] block, a [derived] expression references compartments[i], and at least one subject carries time-varying covariates, or an individual parameter reads TIME (#1855). |
W_DERIVED_CMT_TV_ODE |
warning | The model has an [odes] block, a [derived] expression references compartments[i], and at least one subject carries time-varying covariates, or an individual parameter reads TIME (#1855). |
W_DERIVED_COVARIATE_SHADOW |
warning | A [derived] name shadows a covariate (allowed but may be confusing). |
W_DERIVED_INIT_ANALYTICAL |
warning | The model has no [odes] block, declares an [initial_conditions] baseline, and a [derived] expression references compartments[i]. |
W_DERIVED_STEP_IGNORED |
warning | step= given for a DV-based integral (ignored; DV integrals always use observation times). |
W_DESIGN_DV |
warning | Simulation reader only: one or more EVID=0 rows had a missing DV and were kept as design points to simulate at, so the dataset contributes more rows than a fit of the same file would. |
W_EBE_START_DEPENDENT |
warning | Three triggers. A cold re-solve of the EBEs at the final estimates scores more than 0.05 OFV units worse than the reported objective, or returns a non-finite objective (#833, #2646); the message names the subjects it missed on. |
W_ETA_NOT_DECLARED |
warning | As E_ETA_NOT_DECLARED, but reported without --data, where ferx cannot yet know whether the dataset supplies the column. |
W_EXPERIMENTAL_NN |
warning | The model uses neural-network components ([covariate_nn]), an experimental feature. |
W_EXPERIMENTAL_SDE |
warning | The model uses stochastic differential equations ([diffusion]), an experimental feature. |
W_FD_JACOBIAN_NOT_TIGHTENED |
warning | Some subjects’ finite-difference Jacobian at the final estimates could not be integrated cleanly at no looser than ode_reltol = 1e-8 / ode_abstol = 1e-10 with 32 times ode_max_steps, and was taken at the fit’s own ODE settings, so the OFV may be off. |
W_FILTER_COLUMN_ABSENT |
warning | A [data_selection] condition names a column the dataset does not have. The comparison never matches, so the condition does not select what was meant — and what that costs depends on the key it was written under: an ignore excludes nothing, an accept excludes every row. |
W_FREM_DRAWN_ETA |
warning | A FREM model was simulated with each subject’s η drawn from Ω, covariate η included: by simulate_with_options_diag() without match_method, by simulate_with_uncertainty_diag(), or by an adaptive simulation for the subjects with no supplied η. |
W_GN_NO_RANDOM_EFFECTS |
warning | method = gn as the last estimating stage on a model with no random effects (n_eta = 0). |
W_IG_FLIP_FLOP |
warning | An inverse-Gaussian absorption closed form (one_cpt_ig / two_cpt_ig) with an ODE twin has, at the initial typical values (η = 0) of at least one subject, a disposition rate (CL/V, or the 2-cpt fast rate α) at or above the IG abscissa 1/(2·MAT·CV²). ferx evaluates the equivalent igd ODE model for such parameters, which is correct but slower. |
W_INIT_NOT_REPRESENTABLE |
warning | A declared value the packer itself altered, before any box existed (#1307): the 1e-10 log floor on a θ / Ω-diagonal / Σ / [mixture] override, or the Fisher-z ±3 rail on a free block_sigma correlation. |
W_INIT_OUTSIDE_BOUNDS |
warning | An initial estimate strictly outside one of ferx’s internal rails rather than a declared bound: the hidden 1e9 θ cap, the Ω ±6 (variance ≤ 1.6e5) / off-diagonal ±10 guards, or the Σ [-8, 5] guard. |
W_IOV_NO_OCCASIONS |
warning | The model declares kappa (IOV) parameters and an Ω_IOV is supplied, but some subjects carry no occasion label once iov_occasion has been applied. |
W_IOV_OCC_MISSING |
warning | Some rows in the IOV occasion column had missing or unparseable values; those rows were assigned occasion=0. |
W_KAPPA_WEIGHT_VARIES_WITHIN_OCCASION |
warning | A weighted kappa’s weight expression evaluates to different values (relative difference above 1e-9) at two observation records of the same occasion, or of the same group of the kappa’s level when nested levels are declared. κ is drawn once per occasion or group, so its effective variance Ω_IOV/W is ambiguous; each record is scaled by its own weight. |
W_LEVEL_SUMMARY |
info | Informational, not a finding, so reported with severity info and not counted as a warning (#2387): one row per level of a model with nested levels, outermost first, e.g. `levelARM: 7 groups in 3STUDYgroups (perSTUDYgroup: min 1, median 2, max 4); 1 of 3STUDYgroups holds a singleARMgroup; 1 kappa atARM(K_ARM). | |W_MCEM_MSTEP_FAILED| warning | NLopt failed at least one IMP / IMPMAP weighted M-step, for a reason other than roundoff, so the fit is demoted toconverged: false. | |W_MCEM_MSTEP_FROZEN| warning | A θ or σ owned by the IMP / IMPMAP weighted M-step never left its starting value over the whole run although a step along it still lowers −2 log L by more than 3.84, so that value is not an estimate and the fit is demoted toconverged: false. | |W_MCEM_NOT_SETTLED| warning | An IMP / IMPMAP run stopped at its iteration limit with its objective's floor still falling, or well above the final marginal, or with too few finite iterations to read, so the fit is demoted toconverged: false. | |W_MCEM_OBJECTIVE_ROSE| warning | An IMP / IMPMAP final marginal sits more than 10% of the objective's scale above the lowest value its iterations reached, so the fit is demoted toconverged: false. | |W_MCEM_SETTLING_UNTESTED| warning | An IMP / IMPMAP run of fewer than 30 iterations was too short to test whether the objective settled. | |W_MISSING_DV| warning | One or moreEVID=0rows had a missingDV(./NA/blank) but were not markedMDV=1; they were skipped rather than scored asDV=0. | |W_MODELED_DURATION_NONPOSITIVE| warning | For aRATE=-2dose into compartmentn, the modeled durationD{n}evaluated at that dose's typical-value snapshot (initial θ, η = 0) is at or below1e-8. | |W_MODELED_RATE_NONPOSITIVE| warning | For aRATE=-1dose into compartmentn, the modeled rateR{n}evaluated at that dose's typical-value snapshot (initial θ, η = 0) is at or below1e-8. | |W_NEGATIVE_LAGTIME| warning |predict()/simulate()only: the same finding asE_NEGATIVE_LAGTIME, on entry points that run no data errors. | |W_NN_BARE_OUTPUT_START| warning | A[covariate_nn]block declares noinit, so every output starts at the output activation's value at 0 (0.693 forsoftplus) whatever parameter it feeds. | |W_NN_UNSCALED_INPUT| warning | A[covariate_nn]input whose data, after the block'scenter/scale, reach past where that input alone saturates a hidden unit at the first layer's initial (Glorot) weight scale:3/afortanh,6/aforsigmoid,a = √(6/(fan_in+fan_out)). | |W_NN_WEIGHT_DIRECT_REFERENCE| warning | An expression references a generated[covariate_nn]weight or bias θ directly rather than through the network's declared outputs. | |W_NO_DOSES| warning | Zero dose events parsed across every subject, **although scored observations are present**. | |W_NO_FEASIBLE_EVAL| warning | The outer optimizer finished without one feasible objective evaluation: every trial was rejected by the EBE convergence guard (max_unconverged_frac) or returned a non-finite objective. | |W_NON_STATIONARY_OPTIMUM| warning | The covariance step's Newton decrement at a FOCE / FOCEI / Laplace / Gauss–Newton estimate exceeds 1 OFV unit — one standard error — so the estimate is not a stationary point of its objective and the fit is demoted toconverged: falsewhatever the optimizer's stop said. | |W_NONFINITE_MARGINAL| warning | The importance-sampling marginal −2 log L at the final estimates isNaN, infinite, or past the divergence cutoffs, so the fit is demoted toconverged: false. | |W_NONFINITE_OBJECTIVE| warning | The objective at the final estimates isNaN, infinite, or at or above the1e14divergence cutoff, so the fit is demoted toconverged: falsewhatever the optimizer's stop rule said; the message names which. | |W_ODE_RHS_INTERPRETED| info | Informational, not counted as a warning (severityInfoinwarnings_structured, categoryode_rhs_route). | |W_ODE_RHS_NOT_NATIVE| info | Informational, as above. The[odes]right-hand side compiled but runs as register code rather than native code:FERX_NO_RHS_JIT=1is set, Cranelift cannot target the host, or the native compiler did not build the program. | |W_ODE_SOLVER_DIAGNOSTICS| warning | The ODE solver statistics of that pass (post-fit predictions at the final estimates, or the predict/simulate call at the supplied parameters) show an unclean integration. | |W_ODE_SOLVER_ESCALATION_NOTE| warning | Informational (severityInfoinwarnings_structured).ode_method = autoescalated one or more integration segments to a stiff stepper, and nothing else went wrong: no escalation was rejected, no step clamped at the minimum step size, no segment was unfinished. | |W_OUTPUT_DUPLICATE| warning | A name in[output]is already written to sdtab automatically (e.g.TAFD,TAD, an eta name). | |W_PARSE| warning | A warning the parser recorded while building the model that has no dedicated code. | |W_PER_CMT_UNMATCHED| warning | The other direction of the two above: a compartment the model **declares** an entry for, that no observation is recorded on. | |W_PROFILE_FD_GRADIENT| warning | A fit with aprofiled θ level block, on the analytic gradient route, where the adjoint could not give some subjects the exact gradient of their terms over the profiled levels. | |W_RESIDUAL_CORRELATION_INERT| warning | The model declares a serial residualcorrelationline, but in every subject each block formed by itsbycolumn(s) holds at most one observation. | |W_RESIDUAL_CORRELATION_PARTLY_CONFOUNDED_KAPPA| warning | The same comparison holds in some subjects but not all, e.g.cs by STUDYnext to a kappa atARMwhere some studies have one arm. | |W_RTTE_DEGENERATE| warning | While simulating a repeated-event (RTTE) stream, a subject's expected number of events before the horizon is non-finite or exceeds 1,000,000, so the stream is skipped; or a stream that passed that check produced more than 1,000,000 events, so it is truncated. | |W_SDE_LAGTIME| warning | An absorption lag time on an SDE ([diffusion]) model is not honoured by the filter. | |W_SDE_RESET| warning | EVID=3/4 resets under an SDE[diffusion]model are not honoured. | |W_SIMULATED_FLIP_FLOP| warning | On a transit or inverse-Gaussian absorption closed form with no ODE twin, some simulated individuals with a positive dose before their last observation were evaluated at a sampled η inside the flip-flop regime (or the 2-cpt confluent-eigenvalue corner). | |W_STALLED_AT_INIT| warning | The estimates never left the initial values. The test is the optimizer's own escape test when the result carries one (no packed coordinate moved by 1% of its scaled range), otherwise a comparison of the free θ, Ω and σ against their initial values at 1% relative. | |W_STEADY_STATE_ABSOLUTE_TIME| warning | AnSS=1dose (II > 0) on a model whose[odes]right-hand side reads an **absolute** clock —TAFD,T/t, or the bareTIMEbuilt-in. | |W_STEADY_STATE_II| warning | SS=1 doses with missing / non-positiveII(treated as non-SS). | |W_STEADY_STATE_INFUSION| warning | SS=1 infusion whose length *after bioavailability* exceedsII(overlapping pulses; SS skipped) — the run-in's own test (#1281). | |W_STEADY_STATE_INIT| warning | The model declares an[initial_conditions]baseline and at least one subject has a steady-state (SS=1) dose. | |W_TRANSIT_FLIP_FLOP| warning | A transit absorption closed form (one_cpt_transit/two_cpt_transit) with an ODE twin has, at the initial typical values (η = 0) of at least one subject, a disposition rate (CL/V, or the 2-cpt fast rate α) at or above the transit rateKTR = (n+1)/mtt. ferx evaluates the equivalenttransitODE model for such parameters, which is correct but slower. | |W_TTE_DEGENERATE_HAZARD| warning | While simulating a time-to-event endpoint with an analytic hazard, a subject drew a non-positive or non-finite effective hazard rate. | |W_TTE_SOLVE_FAILED| warning | While simulating a time-to-event endpoint with an ODE-accumulated (drug-driven) hazard, the event-time solve failed for a subject: an[odes]state or the cumulative hazard became non-finite, the hazard went negative, or the solver ran out of steps. | |W_UNCERTAINTY_DRAWS_SKIPPED| warning | Some parameter draws ofsimulate_with_uncertaintyput a transit or inverse-Gaussian closed form with no ODE twin into the flip-flop regime at typical values, where it has no solution, so those draws were not simulated. | |W_UNUSED_PARAM| warning | A user-declared θ, ω or κ is not referenced by any[individual_parameters]or[event_model]expression, or a σ is not referenced in[error_model]. | |W_VI_BAD_BASIN| warning | At the end of amethod = virun, the excess of the sampled data term over its value at the variational means is more than 25 times theΣ dᵢ/2a posterior-shapedqwould give. | |W_VI_OMEGA_UNANCHORED| warning | A method chain containingvisets bothvi_kl = mcandvi_omega_update = adam. | |W_ZERO_DV_MAGNITUDE_ONLY| warning | Observations withDV = 0are scored by a residual error model whose variance is zero at a zero prediction:proportional, apower(…)magnitude, or acombined` model whose additive SD starts at 0. |
Fit object slots
Elements of the list ferx_fit() returns, for a fit of the warfarin example. Some slots are NULL unless the corresponding step or model feature is used. Descriptions are the first sentence of the entry in ?ferx_fit, where it has one.
| Slot | Description |
|---|---|
aic |
Akaike Information Criterion |
bayes |
|
bic |
Bayesian Information Criterion |
bic_inputs |
Named list of the free-parameter tally by Delattre class - n_obs, theta_random, theta_fixed, omega, kappa, sigma, sigma_random - which ferx_bic turns into the mixed / IIV / random BIC variants. |
bloq_method_label |
Character string describing the LOQ-censoring handling method used (“m3”, “drop”, etc.). |
bundle |
The fit’s .fitrx bundle as a raw vector, as ferx-core serialized it. These bytes are the fit: ferx_save_fit writes them, and ferx_covariance, ferx_sir and ferx_calc_npde read them and return a new fit with new ones, so a change made to the list by hand reaches none of these. ferx_load_fit() sets it to the file’s bytes. |
call_settings |
Named list of the effective settings passed to Rust, with values typed back to their natural R types (logical, numeric, or character). |
cond_dist |
|
condition_number |
Ratio of the largest to smallest eigenvalue of the correlation matrix of estimated parameters. |
converged |
Logical; did the optimizer converge. Its stop must also be a stationary point for FOCE, FOCEI, Laplace / AGQ and Gauss-Newton fits (ferx-core #2785). |
cor_matrix |
Correlation matrix derived from cov_matrix, same dimnames. A correlation close to between two parameters flags a structural identifiability problem in the model. |
cov_fixed |
Logical vector, one entry per row of cov_matrix and named like them: TRUE for a coordinate the engine held rather than estimated - a parameter declared FIX, a theta the engine held because it had no effect on the objective (see theta_fixed), a structural-zero covariance of a mixed block omega, or a parameter collapsed onto the internal guard that the covariance step held (see held_at_bound). |
cov_matrix |
Full parameter covariance matrix as a named numeric matrix (params × params). Row/column names use declared variable names (“TVCL”, “ETA_CL”, “EPS_PROP”); fallback is “OMEGA(1,1)” / “SIGMA(1)”. |
covariance_method |
The estimator that produced cov_matrix and the standard errors: “r”, “s” or “rsr”, the [fit_options] token (ferx-core #1382). |
covariance_n_evals_estimated |
Estimated number of OFV calls required for the covariance step, computed before the step runs on large models. |
covariance_status |
String: “computed”, “failed”, “not_requested”, or “sir_fallback” (the finite-difference Hessian was not positive definite and covariance_fallback = “sir” produced SIR-based intervals). |
covariance_wall_time_secs |
Wall-clock seconds spent in the covariance step. On a fresh fit it is part of wall_time_secs. 0 when the step did not run, or when the fit was loaded from a .fitrx bundle written before the field existed. |
covariate_names |
Character vector of non-standard column names present in the dataset (beyond ID, TIME, DV, EVID, AMT, CMT, RATE, MDV, II, SS, CENS, OCC). |
covariate_stats |
Data frame of the statistics a [covariate_model] relation stated symbolically (center = median, ref = mode, levels = auto) was resolved against: one row per covariate a relation reads, summarised over the fitted data (after [data_selection] and ignore). |
covariate_types |
Named character vector mapping each declared covariate to its type, “continuous” or “categorical” (the type from the [covariates] block). |
covtab |
Data frame echoing the declared covariate columns, present only when the model has a [covariates] block. |
data_hash |
|
data_name |
Dataset name, derived as the basename of the data path with its extension stripped. |
data_path |
|
dw_statistic |
Pooled Durbin-Watson statistic for IWRES over pairs of consecutive rows of one subject that share, under a correlation … by line, a residual block. |
ebe_convergence_warnings |
Number of outer iterations in which too many EBEs were unconverged (step was rejected by the guard). |
ebe_etas |
Data frame with one row per subject containing the BSV empirical Bayes estimates: ID plus one column per eta named after the model’s eta declarations (e.g. ETA_CL, ETA_V). |
eigenvalues |
Numeric vector of eigenvalues of the correlation matrix of estimated (non-fixed) parameters, sorted descending. |
estimate_near_boundary |
TRUE when a theta is pinned to a declared bound - the predicate ferx_bootstrap applies as skip_estimate_near_boundary. |
estimates |
Tidy data frame of all estimated parameters (theta, omega diagonal, sigma, - for IOV models - kappa diagonal, and - for a [mixture] model with omega(k) / sigma(k) overrides - one row per override), with columns param, transform, estimate, fixed, se, rse_pct, lower_95, upper_95, estimate_natural, lower_95_natural, upper_95_natural, init_as_sd, weight, scale, level, class. |
eta_linked_theta |
Character vector parallel to eta_names: the typical-value theta each ETA is attached to, or “” when there is none or its statements disagree. |
eta_log_transformed |
Logical vector of length n_eta; TRUE when the eta is lognormally parameterised (THETA * exp(ETA)), FALSE for additive or unknown parameterisations. |
eta_names |
Character vector of ETA parameter names as declared in the model file (e.g. “ETA_CL”, “ETA_V”). |
eta_normality |
Data frame with Shapiro-Wilk normality test for each ETA: columns eta, W, p_val, flag. |
eta_param_types |
Character vector parallel to eta_names: the scale each ETA enters its parameter on, “log_normal”, “additive”, “logit”, “logit_probability” or “custom”. |
eval_budget_spent |
Logical; the outer optimizer spent its evaluation budget. FALSE on a bundle written before it existed. |
evaluation_only |
Logical; no stage estimated - the run scored the given values by request (maxiter = 0, or a standalone imp_eval_only / agq_eval_only chain). |
exclusions |
Named list summarising records excluded by [data_selection] rules (model file and/or ignore/ accept/ignore_ids arguments). |
ferx_version |
ferx-core library version string. |
final_gradient |
Numeric vector containing the gradient of the objective function at the best-OFV parameter point (packed space: log-theta, Cholesky-omega, log-sigma). |
final_gradient_source |
Character scalar saying where final_gradient came from: “optimizer” (the optimizer’s own gradient, evaluated during the fit), “analytic” (the exact gradient, computed after a derivative-free fit) or “finite_difference” (a central difference, computed after a derivative-free fit the analytic gradient does not cover). |
gradient |
The inner-loop gradient method as requested by the caller (usually “auto” or “fd”). |
gradient_method_inner |
Engine label for the inner-loop gradient method. Prefer gradient_used for display. |
gradient_method_outer |
Engine label for the population-level optimizer’s gradient method. |
gradient_used |
The inner-loop gradient method the engine actually used: “analytic”, “fd”, or “N/A” (derivative-free / sampling step). |
held_at_bound |
Data frame of every parameter the covariance step reports no standard error for (ferx-core #2797), one row each, with columns parameter (its name in the estimates), kind (“theta”, “omega”, “sigma” or “kappa”), index (1-based, within its family) and reason: “profiled_bound” for a profiled level on its declared bound, “collapsed_at_guard” for a variance or sigma collapsed onto the floor of its log packing, or a theta with no declared lower bound on the internal 1e-10 floor, and “unknown” for a reason a later ferx added. print(), fit$estimates and ferx_runlog() show each one’s SE as N/A / NA. |
imp_seed |
Numeric scalar (or NULL) giving the importance sampling seed. NULL when IS was not run. |
impmap_trace |
|
importance_sampling |
Importance-sampling marginal log-likelihood diagnostics, populated only when the method chain ends with an “imp” or “impmap” stage (NULL otherwise). |
individual_estimates |
Data frame with one row per subject containing each subject’s individual parameter values: ID plus one column per parameter declared in the [individual_parameters] block (e.g. CL, V, KA). |
inits_from_nca |
Character string giving the NCA initialisation method used (“nca”, “nca_sweep”, or “nca_ebe”), or NULL when model-file initial values were used directly. |
input_columns |
Includes both standard columns (ID, TIME, DV, etc.) and any covariate columns. Empty for in-memory fits that never read a file and absent after a ferx_save_fit/ferx_load_fit round-trip on older bundles. |
interaction |
Logical; the interaction flag the fitted objective ran under. TRUE for FOCEI and FALSE for FOCE; SAEM, VI and Gauss-Newton inherit it from the options they ran under. ferx_covariance() and ferx_sir() hand it back to the engine. |
iov_occasion |
Character string giving the IOV occasion rule the fit derived its occasions with, in the spelling settings = list(iov_occasion = …) takes: “column”, “dose” or “time(24, 48)”. |
iwres_lag1_r |
Pooled lag-1 Pearson correlation of IWRES over the same pairs as dw_statistic. Positive values indicate under-fitting, negative values indicate over-fitting. |
kappa_fixed |
Logical FIX flag per kappa, parallel to kappa_names; empty when the model has no IOV. |
kappa_init_as_sd |
Logical vector, one entry per IOV kappa parameter. Same semantics as omega_init_as_sd for inter-occasion variability. |
kappa_is_diagonal |
The same flag for the IOV (KAPPA) block; NA when the model declares no IOV. |
left_init |
The outer optimizer’s own verdict on whether it left the initial estimates: TRUE, FALSE, or NA when the method recorded none. |
max_abs_correlation |
Largest absolute off-diagonal of the covariance matrix in correlation form, on the natural theta / OMEGA / SIGMA scale. |
max_unconverged_subjects |
Worst-case number of unconverged subjects in a single outer iteration. |
method |
Estimation method used |
method_chain |
|
mixture_override_params |
Data frame naming each entry of mixture_overrides, one row each and in its order (ferx-core #2833): parameter (<base> (class <k>), the label cov_matrix and held_at_bound use), kind (“omega” or “sigma”), index (1-based, of the base parameter it overrides within its family), class (1-based) and fixed (TRUE for a FIX override, or a sigma override SAEM held at its initial value). |
mixture_overrides |
Numeric vector: a [mixture] fit’s fitted per-class overrides, one class variance per omega(k) override and then one class sigma per sigma(k) override, in declaration order (every estimator, SAEM included); NULL for a model without overrides. |
model_file_settings |
Named list of raw key = value pairs from the model file’s [fit_options] block, as character strings (before Rust type coercion). |
model_hash |
|
model_name |
Model name declared in the .ferx file by a top-level model <name> line (outside any [block], e.g. model warfarin_pk); the name is a single word. |
model_path |
|
model_source |
|
model_structure |
Named list returned by the Rust engine, derived from the parsed CompiledModel so it reflects exactly what ferx-core ran. |
model_text |
Verbatim content of the .ferx model file as a character string. NULL for in-memory fits that were never associated with a file, or for fits produced by older engine versions. |
multi_start_seed |
Numeric scalar (or NULL) giving the random seed used for multi-start parameter perturbation. |
n_iterations |
Number of outer iterations run |
n_obs |
|
n_parameters |
|
n_starts |
Integer. Number of multi-start runs attempted. 1 for single-start fits. |
n_subjects |
|
n_threads_used |
Integer. Width of the worker pool the engine ran the fit on: the threads argument, else the model file’s [fit_options] threads, else the engine default. |
neural_networks |
Named list of sub-lists, one per [covariate_nn] block declared in the model file. |
nlopt_missing_algorithms |
Character vector of NLopt algorithm names that are not available in the current build (empty on most platforms). |
obs_time_range |
Length-2 numeric vector c(min_time, max_time) across all observation records, or NULL when there are no observations. |
ode_linear_exact |
Logical; TRUE when the [odes] system was linear and solved exactly by the matrix exponential at the final estimates instead of integrated (ode_method = “auto” on a linear model, or ode_method = “linear”), with no segment falling back to integration. |
ofv |
Objective function value (-2 log-likelihood). The penalized objective when the model declares a prior(…) on any parameter, i.e. ofv_data + ofv_prior. |
ofv_data |
The data half of ofv - the -2 log-likelihood the AIC and BIC are computed from, and the value to compare against an unpriored fit of the same model. |
ofv_prior |
The prior half of ofv: the penalty summed over the priored coordinates. Exactly 0 when no prior is declared. |
omega |
Between-subject variability covariance matrix. Row and column names are the declared ETA names (e.g. “ETA_CL”); fallback is “OMEGA(1,1)” when names are absent. |
omega_fixed |
Logical FIX flags, one per theta, per eta (the omega diagonal; every eta of a fixed block is TRUE) and per sigma. |
omega_init |
Initial omega variance matrix, same layout as omega. A zero matrix for in-memory fits and older bundles. |
omega_init_as_sd |
Logical vector, one entry per BSV eta. TRUE when the corresponding omega line in the model file was annotated with (sd), meaning the initial value was specified as a standard deviation rather than a variance. print.ferx_fit() appends [initial specified as SD] to those rows. |
omega_init_dim |
Number of rows/columns of omega_init. |
omega_is_diagonal |
TRUE when the OMEGA block the fit was estimated under is diagonal, FALSE for a block_omega model, NA when the engine recorded no layout. |
optimizer_label |
Human-readable label for the outer optimizer used (e.g. “LBFGS”, “BOBYQA”). Mirrors the optimizer enum value from ferx-core. |
outer_gtol |
Numeric. Gradient tolerance passed to the outer optimizer. |
outer_maxiter |
Integer. Maximum number of outer-loop iterations passed to the optimizer. |
packed_estimate |
Numeric vector: the optimizer’s estimate on its packed scale (FOCE, FOCEI, Laplace and Gauss-Newton fits; NULL otherwise). ferx_covariance starts from it, which makes its result identical() to the inline covariance step. |
population_fingerprint |
Character strings holding the engine’s JSON record of how the fit read its data (the model file’s [data_selection] with ignore, accept, ignore_ids and settings = list(iov_column = …) merged in) and a fingerprint of the population it read (about 270 bytes per subject). |
prior_summary |
Per-parameter prior report, or NULL when the model declares no prior. One row per priored parameter with columns name, prior_value, estimate, shift_in_prior_sds (signed, in prior SDs), penalty (this parameter’s contribution to ofv_prior), family (“lognormal” or “normal”, decided by the parameter’s declared lower bound), and the implied 95% prior interval prior_lower_95 / prior_upper_95. |
profiled_blocks |
Character vector naming the level blocks declared theta NAMECOL, … profile, in declaration order; character(0) for a fit without one. |
profiled_levels_at_bound |
Character vector of the theta names of the profiled levels that ended exactly on their block’s declared bound (ferx-core #2112); character(0) when none did. |
reader_settings |
Character strings holding the engine’s JSON record of how the fit read its data (the model file’s [data_selection] with ignore, accept, ignore_ids and settings = list(iov_column = …) merged in) and a fingerprint of the population it read (about 270 bytes per subject). |
saem_mu_ref_m_step_evals_saved |
Number of OFV evaluations saved by mu-referencing in the SAEM M-step. Only populated for SAEM fits with mu_referencing = TRUE; NULL otherwise. |
saem_n_subjects_hmc |
Integer count of subjects whose SAEM E-step proposals were generated by HMC (i.e. n_leapfrog > 0 and the AD build is active). |
saem_seed |
Numeric scalar (or NULL) giving the SAEM stochastic seed. NULL for non-SAEM methods. |
scoring_settings |
Named list of the inner-loop and ODE settings the stage that produced the estimates scored the objective under: inner_maxiter, inner_tol (as the stage ran it, after the tightening ferx applies for LTBS and quadrature), inner_restarts, inner_screen, inner_twin_seed, mu_referencing, n_agq, inner_optimizer, ebe_warm_start, ode_reltol, ode_abstol, ode_max_steps, ode_method, ode_stiff_abort_after (NA when off), ode_auto_switch, gradient_method (the gradient route the fit took, “auto” or “fd”), and nn_l2_lambda / nn_smooth_lambda (the [covariate_nn] penalty strengths the objective carried, ferx-core#1352; a recorded one is kept by ferx_covariance() whatever its arguments, NA when unrecorded), with the values [fit_options] spells. ferx_covariance scores under them, and ferx_save_fit keeps them. |
sdtab |
Data frame with ID, TIME, DV, PRED, IPRED, CWRES, IWRES, EBE_OFV, N_OBS; OCC if any subject carries an occasion column; CENS if any rows are LOQ-censored; CMT if the dataset has more than one endpoint (any observation with CMT != 1). |
se_mixture_overrides |
Numeric vector: the standard errors of mixture_overrides, parallel to it, named like it and on its scales (a class variance, a class sigma; ferx-core #2833). |
se_omega |
Standard errors for omega elements. For diagonal omega, a vector of length n_eta (one per variance). |
se_sigma |
Standard errors for sigma (on the SD scale, like sigma itself). Named like sigma. |
se_theta |
Standard errors for theta (NULL if covariance step failed) |
shrinkage_eps |
EPS shrinkage: 1 - SD(IWRES). NA when fewer than 2 valid residuals. |
shrinkage_eta |
Numeric vector of ETA shrinkage per random effect (1 - SD(eta_hat_k) / sqrt(omega_kk)). |
sigma |
Residual error parameter estimates on the standard-deviation scale. For a proportional component CV% = sigma * 100; for an additive component the value is in observation units. |
sigma_fixed |
Logical FIX flags, one per theta, per eta (the omega diagonal; every eta of a fixed block is TRUE) and per sigma. |
sigma_init |
Numeric vector of initial sigma values, parallel to sigma and sigma_names. |
sigma_init_as_sd |
Logical vector, one entry per sigma component. Same semantics as omega_init_as_sd for residual-error parameters. |
sigma_names |
Names of the sigma parameters as declared in the [parameters] block of the .ferx file. |
sigma_types |
Per-component error type label, parallel to sigma: “proportional” or “additive”. |
sir_seed_used |
Numeric scalar giving the seed SIR resampled with: sir_seed, or the built-in default 12345 when sir_seed was unset. |
sir_settings |
Named list of the settings the fit’s SIR ran under: samples, resamples, seed (resolved: 12345 when sir_seed was unset), df, scale, keep_samples, and scoring, the inner-loop and ODE settings each draw was scored with, shaped as scoring_settings. ferx_sir repeats this SIR by default and records its own run here; ferx_save_fit keeps it. |
stalled_at_init |
TRUE when no free parameter moved more than 1% of its initial value, when the fit carries nothing to judge by. |
stationary_start |
TRUE when a fit that did not leave its start was restarted from a perturbation of it and converged back to the same objective: a warm start at an optimum (a bootstrap replicate, a refit from earlier estimates), not a stall. |
status |
The engine’s verdict on whether the fit can be used as it stands (ferx-core #2799): “converged”, “converged_with_issues” or “not_converged”. |
status_label |
status as the console spells it: “CONVERGED”, “CONVERGED WITH ISSUES”, “NOT CONVERGED”. |
status_reasons |
Character vector of what qualifies status, in the engine’s fixed order: “evaluation_only” (the run scored the given values, e.g. maxiter = 0), “budget_spent” (the optimizer ran out of evaluations), each critical warning’s category (e.g. “parameter_at_runaway_guard”), “covariance_failed”, and “collapsed_at_guard: ETA_KA” for a collapse the covariance step ran on but did not hold. |
subject_ids |
Character vector of every subject’s ID, verbatim from the data and in fit order (the rows of ebe_etas). |
subject_summary |
Data frame with one row per subject, in fit order (the entries of subject_ids): ID; ofv_contribution, the subject’s contribution to the OFV; n_obs, its continuous (Gaussian) observations; n_obs_discrete, its discrete (binary) observation records; and n_obs_tte, its time-to-event records. sdtab holds each subject’s n_obs rows in subject order, then each subject’s n_obs_discrete rows in subject order, then each subject’s n_obs_tte rows. |
theta |
Named numeric vector of fixed effect estimates. A free level of a theta NAME[COL, …] level block is named NAME[COL=value,…], e.g. PLACEBO[STUDY=1,TIME=4]. |
theta_fixed |
Logical FIX flags, one per theta, per eta (the omega diagonal; every eta of a fixed block is TRUE) and per sigma. |
theta_init |
Numeric vector of initial theta values as supplied to the optimizer, parallel to theta and theta_names. |
theta_levels |
Data frame with one row per level of each theta NAME[COL, …] level block, as the block was bound to the fitted data (after [data_selection] and ignore), with columns block, index (1-based level position within the block), label (COL=value,…), group (contrast group, 0-based), contrast (the resolved convention: “sum_to_zero”, “sum_to_zero_within”, “ref” or “none”), profiled (TRUE on every level of a block declared profile: its levels were solved for at every outer step rather than searched by the optimizer, see profiled_blocks), theta_name (the level’s name in theta, NA for a level the contrast derives from the others) and value (the level’s fitted value, derived levels included: minus the sum of its group’s free levels under sum_to_zero / sum_to_zero_within, 0 for a ref reference level. |
theta_transforms |
|
total_ebe_fallbacks |
Total Nelder-Mead fallback invocations across all subjects and iterations. |
uses_ode_solver |
Logical; TRUE when the model has an [odes] block, FALSE for an analytical model. |
uses_sde |
Logical; TRUE when the model file contained a [diffusion] block and the fit used the Extended Kalman Filter (EKF) likelihood. |
wall_time_secs |
Total wall-clock time for the fit in seconds. |
warning_details |
List of the engine warnings that carry a structured details payload (ferx-core #2268), one named list per warning with severity, category, message, source_method (when set) and details - for example the full unusable_subjects list of W_NONFINITE_OBJECTIVE, whose message names at most ten. ferx_save_fit keeps it, in the .fitrx slot ferx-core writes, and ferx_get_warnings(as_df = TRUE) shows each payload beside its warning. |
warnings |
Character vector of warnings |
warnings_category |
|
warnings_message |
|
warnings_severity |
|
warnings_source_method |
|
warnings_structured |
Data frame with columns severity (“critical”, “warning”, or “info”), category (a fixed vocabulary such as “convergence”, “covariance_step”, “dw_autocorrelation”), message, and source_method (the estimation stage that emitted the warning, e.g. “FOCEI”; empty string when not applicable). |
Not available from R
Features documented for ferx-core that the pinned ferx-r build cannot run, or runs only partly:
| Feature | Status at the pinned build | Where to look |
|---|---|---|
Variational inference as ferx_fit(method = "vi") |
The method argument rejects it; method = vi in [fit_options] runs |
Estimation methods and controlling the fit |
[markov_model] (continuous-time Markov endpoints) |
Rejected at parse time: ferx-r does not build the engine’s markov feature |
Markov models |
[simulation] block |
Read by the ferx-core command line only; ferx-r’s simulation functions need a dataset | Simulating scenarios |
[dynamics_nn] (neural-network ODE terms) |
Not implemented (design only) | Neural networks |
Hand-written [covariate_model] relations, repeated time-to-event, fixed-rate infusions into the central compartment |
Fit from R, but no bundled ferx-r example | Covariate modeling, Time-to-event models, Dosing regimens and exposure metrics |
[mixture] models, modelled infusion rate or duration (RATE = -1, -2) |
No bundled example | Variability: random effects, residual error and IOV, data format |
| VI’s ELBO and per-subject posterior summaries | Not on the R fit object | Variational inference |
Feature maturity
The maturity label of each ferx-core feature at the pinned engine (ferx-core a959f4b6). stable features are well tested across datasets and estimation options; beta features are stable in limited testing; experimental features have been tested on a few examples and may change. See the ferx-core feature maturity page.
| Feature | Maturity | ferx-core page |
|---|---|---|
| Parameters (theta / omega / sigma, block omega) | stable | Parameters |
| Inter-occasion variability (IOV) | stable | IOV |
| Covariates | stable | Covariates |
| Structural model — analytical PK (1/2/3-cpt) | stable | Structural Model |
| Lag time | stable | Lagtime |
| Steady-state doses (SS) | stable | Steady-State Doses |
| Multiple dosing (ADDL / II) | stable | Multiple Dosing |
| Error model (additive / proportional / combined) | stable | Error Model |
| Simulation | stable | Simulation |
| Individual parameters DSL | beta | Individual Parameters |
| BLOQ / censored observations (M3) | beta | BLOQ |
| ODE models (Dormand-Prince RK45) | beta | ODE Models |
Stiff ODE steppers (ode_method = Rosenbrock23 / Rodas4 / Rodas5P) |
beta | Stiff systems |
High-order ODE stepper (ode_method = Vern7) |
experimental | Choosing a method |
Automatic stiff-solver selection (ode_method = auto, the default) |
beta | Letting ferx pick the stepper |
| Built-in absorption models (transit / inverse-Gaussian / Weibull) | beta | Absorption |
| Scaling | beta | Scaling |
| Data selection | beta | Data Selection |
| Derived columns | beta | Derived Columns |
| Output columns | beta | Output Columns |
| Time-to-event endpoints (TTE) | beta | Time-to-Event Endpoints |
| Stochastic differential equations (SDE) | experimental | SDE |
| Neural networks (DCM / NODE) | experimental | Neural Networks |
Adaptive (feedback) dosing — [adaptive_dosing] block / simulate_adaptive() |
beta | Adaptive Dosing |
| FOCE / FOCEI | stable | FOCE / FOCEI |
Gauss-Newton (BHHH) — gn, gn_hybrid |
beta | Gauss-Newton |
| SAEM | beta | SAEM |
| SIR | beta | SIR |
| Importance sampling (IMP) | beta | Importance Sampling |
| Outer optimizers (BOBYQA, SLSQP, L-BFGS, MMA, trust-region) | beta | Outer Optimizers |
| Time-to-event estimation (TTE) | beta | Time-to-Event |
θ level blocks (theta NAME[LEVEL]; sum_to_zero / sum_to_zero_within / contrasts; per-level SEs) |
beta | Theta level blocks |
profiled level blocks (incl. bounded) |
beta | Profiled level blocks |
Nested variability levels (level … in …, kappa … at LEVEL) |
beta | Nested levels |
Within-arm residual correlation (cs / ar1 / car1, incl. with a kappa) |
beta | Within-group residual correlation |
Residual weight = and kappa weight = |
beta | Residual weighting, Sample-size-weighted IOV |
Compartment-free (algebraic) [structural_model] |
beta | Compartment-Free Models |