Feature Maturity
Not every feature in ferx-core is equally battle-tested. Some — like FOCE/FOCEI estimation and the analytical PK solutions — have been validated against gold standard engines across many datasets. Others are newer and have only been exercised on a handful of examples. To make this explicit, every major feature carries a maturity label.
Where a feature has its own dedicated reference page, that page repeats its label in a banner at the top, e.g.:
Maturity: beta — see Feature Maturity for what this means.
The table below is the authoritative list; a few features documented inside a shared reference page (e.g. the gradient method under Fit Options) or only in an example carry their label here rather than in a per-page banner.
Maturity levels
| Label | Meaning |
|---|---|
| stable | Well-tested functionality with proven stability across diverse datasets and estimation options. Performance is comparable to (or better than) gold standard NLME engines (NONMEM, Monolix). Safe for production use. |
| beta | Stable in limited testing and across a range of fit settings, but some caution is warranted before relying on it in production on unseen datasets. Validate against a reference where you can. |
| experimental | New functionality tested only on a single example or a small handful of (often toy) examples. Behaviour and syntax may change. Results should be treated as provisional and validated carefully. |
These labels describe ferx-core’s current state and will move upward as features accumulate testing and cross-validation. Most of ferx-core is currently beta, with a mature core approaching stable; a few features remain experimental.
Runtime warnings
Two experimental features emit a warning at fit time (surfaced in FitResult.warnings, the CLI output, and ferx check) so their status is visible at the point of use. The others are flagged only by their label here and on their reference page:
| Feature | Warning code |
|---|---|
Stochastic differential equations ([diffusion]) |
W_EXPERIMENTAL_SDE |
Neural networks ([covariate_nn]) |
W_EXPERIMENTAL_NN |
Beta and stable features do not emit a maturity warning.
Feature reference
Model file features
| Feature | Maturity | Reference |
|---|---|---|
| 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 |
Estimation features
| Feature | Maturity | Reference |
|---|---|---|
| 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 |
Model-based meta-analysis (MBMA) features
The pieces of an MBMA model, in the order Model-based meta-analysis: start here introduces them. Each is labelled beta on the strength of the NONMEM anchor named in its row (catalogued in nonmem_anchor/README.md); the anchors cover single models, not the range of datasets stable asks for.
| Feature | Maturity | Reference | NONMEM anchor |
|---|---|---|---|
θ level blocks (theta NAME[LEVEL]; sum_to_zero / sum_to_zero_within / contrasts; per-level SEs) |
beta | Theta level blocks | level_two_block, level_se_{a,b}, level_no_gaussian (read by a TTE hazard) |
profiled level blocks (incl. bounded) |
beta | Profiled level blocks | profile_mbma, profile_mbma_bound, profile_mbma_tve0_55; with a correlation line, no NONMEM run: it matches the anchored unprofiled fit (With a profiled level block) |
Nested variability levels (level … in …, kappa … at LEVEL) |
beta | Nested levels | nested_levels_3 (OFV, EBEs), nested_levels_3_cov (R-matrix SEs) |
Within-arm residual correlation (cs / ar1 / car1, incl. with a kappa) |
beta | Within-group residual correlation | residual_correlation/* (naproxen, real data); nested_levels_3_ar1/* (with kappa) |
Residual weight = and kappa weight = |
beta | Residual weighting, Sample-size-weighted IOV | mbma_canakinumab (both, real data); residual_correlation/* (residual); nested_levels_3 (kappa) |
Compartment-free (algebraic) [structural_model] |
beta | Compartment-Free Models | algebraic_emax vs $PRED |
For the MBMA group, a feature’s section banner and its row in this table must agree; when one changes, change the other in the same PR.
The label reflects the engine’s overall confidence in a feature, not the presence or absence of tests — a beta feature may still have extensive automated tests; “stable” additionally requires broad cross-validation against reference engines across diverse datasets.