FeRx NLME - R package (ferx)

Preface

This book teaches nonlinear mixed-effects (NLME) modeling with ferx, an R package whose estimation and simulation engine is written in Rust (ferx-core). It is organised as an analysis workflow. You follow a project from the raw dataset to a report, and every step is a piece of R code you can run.

About this book

The book is about using ferx in R: which function to call at each stage of an analysis, what comes back, and how to turn it into diagnostics, simulations and tables. The model language, estimation algorithms and every option are specified in the ferx-core documentation. The book links there for the full technical detail rather than repeating it.

Every code chunk is executed when the book is built, and every output shown is the real result of that code. The examples use the models and datasets bundled with the package (ferx_example()), so you can run them yourself.

The workflow

The chapters follow the stages of a modeling analysis:

Stage What happens Chapters
Data prepare, check and select records Preparing and checking the analysis dataset
Model write, inspect and edit the model file Writing and managing model files
Estimate initial estimates, fitting, estimation methods Initial estimates and a first fit, Estimation methods and controlling the fit
Evaluate diagnostics, VPCs, model selection, parameter uncertainty Diagnosing the model, Simulation-based evaluation: VPC, Model development and selection, Parameter uncertainty
Simulate predictions and scenario simulations Simulating scenarios
Report tables, figures, saving and sharing results Tables and figures, Reproducibility and sharing

Estimation and evaluation form a loop: you fit, evaluate, revise the model and fit again. A complete analysis in one chapter runs the whole workflow once on a small example. After that, The analysis workflow covers each stage in depth.

The scenario Parts apply the same workflow to specific modeling problems, grouped by category:

Function, option and example index lists every function, fit setting, model block, data column, bundled example and warning category, with the chapter that covers it, plus the fit object’s slots and the parser’s check codes, which belong to no single chapter.

Finding things

If you arrived with a question rather than a project, start here.

You want to Go to
Check a dataset, or exclude records and subjects Preparing and checking the analysis dataset
Write, inspect or edit a model file, or validate one Writing and managing model files
Choose starting values, run a first fit, read what came back Initial estimates and a first fit
Change the estimation method, settings, or run fits in parallel Estimation methods and controlling the fit
Judge a fit: goodness of fit, residuals, shrinkage, conditioning Diagnosing the model
Run a visual predictive check Simulation-based evaluation: VPC
Compare candidate models, or let a search choose Model development and selection
Get standard errors, confidence intervals, a bootstrap or a posterior Parameter uncertainty
Simulate a regimen, a trial design or a new population Simulating scenarios
Build the tables and figures of a report Tables and figures
Save, reload and share a fit Reproducibility and sharing
Choose an analytical model or write ODEs; scale a readout Structural models: analytical and ODE
Model absorption: lag, transit, zero-order, bioavailability Absorption and bioavailability
Add between-subject, occasion or residual variability Variability: random effects, residual error and IOV
Hold a parameter at a fixed value, when the data cannot identify it Absorption and bioavailability
Add covariates, allometry or a FREM model Covariate modeling
Handle repeated doses, steady state, infusions; derive AUC or Cmax Dosing regimens and exposure metrics
Handle observations below the limit of quantification Censored observations (BLOQ)
Fit a PD endpoint alongside PK PK/PD and multiple endpoints
Fit a binary endpoint Binary endpoints
Fit a time-to-event endpoint Time-to-event models
Simulate dose adjustment from measured concentrations Adaptive dosing and TDM strategies
Try an experimental feature: system noise (SDE) or a neural-network covariate model Experimental features

And when something needs looking up rather than reading, Function, option and example index has one table each for: what a function or its arguments do, what a setting means and defaults to, what a warning category means and how serious it is, what an error code means, what a model file block is for, and what a data column holds.

The pinned build

ImportantVersion

This book was built with ferx-r commit 6e2f701 (package version 0.3.0), which embeds ferx-core d66046e. Installing ferx shows how to install exactly this build.

The linked ferx-core documentation follows the engine’s development branch, so it can describe features that are newer than this build.

Prerequisites

You should be comfortable with R, including data frames, dplyr and ggplot2, and with the basics of population pharmacokinetics: compartment models, between-subject variability and residual error. Besides ferx, the book uses these R packages:

book_packages <- c("ggplot2", "dplyr", "tidyr", "patchwork", "gt", "survival")
data.frame(package = book_packages,
           version = vapply(book_packages, function(p) as.character(packageVersion(p)), ""),
           row.names = NULL)
#>     package version
#> 1   ggplot2   4.0.3
#> 2     dplyr   1.2.1
#> 3     tidyr   1.3.2
#> 4 patchwork   1.3.2
#> 5        gt   1.3.0
#> 6  survival  3.8.12

Conventions

  • Lines starting with #> are output printed by the code above them.
  • Each chapter ends with a Reference box that points to the R help pages (?function) and the ferx-core documentation for that topic.
  • Features that ferx-core labels beta or experimental carry a callout with that label. The ferx-core feature maturity page defines the levels.
  • The R help pages of your installed build (?ferx_fit, ?ferx_simulate, …) are the complete reference for every function argument.