Get paths to example model and data files

Description

Returns file paths to bundled example models and datasets. Called without arguments, lists available example names.

Usage

ferx_example(name = NULL)

Arguments

  • name: Name of the example (e.g. “warfarin”). If NULL, returns a character vector of available example names.

Details

Available bundled examples:

  • warfarin: One-compartment oral PK (standard warfarin dataset)
  • warfarin_bloq: One-compartment oral with BLOQ observations (M3 method)
  • warfarin_iov: One-compartment oral with inter-occasion variability (kappa)
  • warfarin_block_omega: One-compartment oral with correlated random effects
  • warfarin_saem: One-compartment oral estimated with SAEM
  • warfarin_additive_eta: One-compartment oral with additive ETA on lag time
  • warfarin_logit_f: One-compartment oral with logit-normal bioavailability
  • warfarin_if: Two-compartment oral with conditional if/else covariate (WT)
  • one_cpt_iv: One-compartment IV (analytical one_cpt_iv)
  • two_cpt_iv: Two-compartment IV bolus
  • two_cpt_oral_cov: Two-compartment oral with continuous covariates (WT, CRCL)
  • three_cpt_iv: Three-compartment IV bolus
  • three_cpt_oral: Three-compartment oral (analytical three_cpt_oral)
  • one_cpt_iv_ode, warfarin_ode, two_cpt_iv_ode, two_cpt_oral_cov_ode, three_cpt_iv_ode, three_cpt_oral_ode: ODE-form transcriptions of the standard analytical models (one_cpt_iv, warfarin = one-cpt oral, two_cpt_iv, two_cpt_oral_cov, three_cpt_iv, three_cpt_oral). Each shares its analytical counterpart’s dataset and parameters; states are amounts and the observed concentration is read out with [scaling] obs_scale = V (or V1). The two forms give identical predictions - verified by test-ode-analytical-equivalence.R.
  • mm_oral: One-compartment oral with Michaelis-Menten elimination (ODE)
  • warfarin_sde: One-compartment oral as ODE with SDE process noise ([diffusion] block, EKF likelihood; DIFF_CENTRAL in theta)
  • mm_multistart: One-compartment oral with Michaelis-Menten elimination (ODE); starting values intentionally far from truth to demonstrate multi-start (n_starts, start_sigma, multi_start_seed in settings)
  • bioavailability: One-compartment oral with logit-normal bioavailability F (analytical; THETA_F specified directly on the (0,1) scale)
  • bioavailability_ode: ODE equivalent of bioavailability - same model and data via explicit depot/central ODEs; useful for comparing analytical vs ODE paths
  • warfarin_dcm: Two-compartment oral with a Deep Compartment Model covariate model: a small neural network ([covariate_nn TYPICAL_PK]) reads WT + CRCL and outputs a multiplicative modulator on the baseline TVCL/TVV1/TVQ/TVV2/TVKA thetas (i.e. CL = TVCL * TYPICAL_PK.CL * exp(ETA_CL)), with lognormal IIV on top. Requires ferx-r built with the nn cargo feature.
  • warfarin_scaled: One-compartment oral (warfarin) demonstrating the [scaling] block (Form A). The dataset records AMT in micrograms (100 mg = 100,000 ug) while DV is in mg/L; obs_scale = 1000 divides model predictions by 1000 so residuals are on the mg/L scale. Estimates should match the standard warfarin example.
  • warfarin_iov_saem: One-compartment oral (warfarin) with inter-occasion variability estimated by SAEM. Identical model to warfarin_iov but uses method = saem; demonstrates that SAEM fully supports IOV kappa parameters.
  • warfarin_ltbs: One-compartment oral (warfarin) with log-transform-both-sides (LTBS) residual error written as log(DV) ~ additive(SIGMA_LOG). The engine log-transforms observations and predictions and fits additive (normal) error on the log scale; the residual is reported as "additive (log-transformed)".
  • warfarin_ss: One-compartment oral (warfarin) demonstrating steady-state dosing. The dose row in the dataset has SS = 1 and II = 24 (once-daily interval). The engine resolves steady-state initial conditions automatically; no model changes are needed.
  • transit_2cpt: Two-compartment ODE model with 3-transit-compartment absorption, allometric scaling on CL/V1/V2 (reference WT = 70 kg). Transit compartments provide the absorption delay without a hard lag time.
  • igd_inverse_gaussian: One-compartment ODE model with Freijer & Post inverse-Gaussian absorption via the built-in igd(mat, cv2) input rate fed straight into central (the entire absorption delay in one term, no first-order ka). Paired with the NONMEM igd anchor dataset.
  • biphasic_igd_absorption: One-compartment ODE model with biphasic inverse-Gaussian (Freijer & Post) absorption: two igd(...) pathways (a fast and a slow one) feeding central, split by a declared pathway fraction (FR1*igd(...) + FR2*igd(...), FR2 = 1 - FR1). Demonstrates the shared input-rate fraction multiplier (ferx-core #388). Shares the NONMEM absorption anchor dataset (syntax demo, mildly mis-specified).
  • weibull_absorption: One-compartment ODE model with Weibull absorption via the built-in weibull(td, beta) input rate fed straight into central (the entire absorption delay in one term, no first-order ka); the shape beta selects the profile. Shares the NONMEM absorption anchor dataset.
  • zero_order_absorption: One-compartment ODE model with zero-order (constant-rate) absorption via the built-in zero_order(dur) input rate – a modeled-duration infusion (NONMEM RATE=-2/D1) fed straight into central. Shares the NONMEM absorption anchor dataset.
  • parallel_absorption: One-compartment ODE model with parallel (dual first-order) absorption: two first_order(ka) pathways (a fast and a slow one) feeding central, split by a declared pathway fraction (FR1*first_order(...) + FR2*first_order(...), FR2 = 1 - FR1). first_order(ka) exposes the classic first-order (Bateman) absorption as a composable input rate (ferx-core #505). Shares the NONMEM absorption anchor dataset (syntax demo, mildly mis-specified).
  • mixed_absorption: One-compartment ODE model with mixed (zero-order + first-order) absorption: a zero_order(dur) input plus a first_order(ka) input feeding central, split by a declared pathway fraction (FZO1*first_order(...) + FZO*zero_order(...), FZO1 = 1 - FZO) (ferx-core #505). Shares the NONMEM absorption anchor dataset (syntax demo, mildly mis-specified).
  • sequential_absorption: Sequential (zero-order then first-order) absorption: zero_order(dur) fills a depot, which empties to central by first-order ka (no dedicated keyword – a composition). Paired with its own simulated dataset (sequential_absorption/simulate_dataset.R), dosing the depot (CMT 1) and observing central (CMT 2).
  • transit_savic: One-compartment oral ODE model with Savic transit-compartment absorption via the built-in transit(n, mtt) input rate. The number of transit compartments n is a single continuous (estimable) parameter, in contrast to transit_2cpt’s hand-coded chain of fixed integer compartments. Paired with the ferx-core transit anchor dataset (correct-specification parameter recovery).
  • tte_exponential: Standalone time-to-event (TTE) model with an exponential hazard via the [event_model] block. Event times on CMT 2 follow Exp(LAMBDA) with LAMBDA = TVLAMBDA * exp(ETA_LAMBDA); DV codes the censoring status (0 = right-censored, 1 = exact event). Paired with the ferx-core TTE anchor dataset (administrative censoring at t = 30 h; recovers TVLAMBDA = 0.05).
  • tte_weibull: Standalone TTE model with a Weibull hazard via the [event_model] block, written in the compact TTE-only form (no [structural_model] / [error_model] / [individual_parameters] blocks). Event times on CMT 2 follow Weibull(scale, shape) with scale = TVSCALE * exp(ETA_SCALE) and shape = TVSHAPE. Paired with the ferx-core TTE anchor dataset (censoring at t = 60 h; recovers TVSCALE = 20, TVSHAPE = 1.5). The compact TTE-only syntax requires a recent ferx-r; older builds need placeholder PK blocks (cf. tte_exponential).
  • tte_gompertz: Standalone TTE model with a Gompertz hazard (h(t) = alpha * exp(gamma * t)) via the [event_model] block, compact TTE-only form. BSV is on the growth rate gamma (not the intercept alpha, which is collinear with it). Paired with the ferx-core TTE anchor dataset (recovers TVALPHA = 0.002, TVGAMMA = 0.05).
  • tte_competing_risks: Competing-risks TTE with two cause-specific exponential hazards on separate compartments (CMT 2 / CMT 3) linked by a shared frailty ETA_F, via two named [event_model] blocks. The observed event is whichever cause occurs first. ferx_predict_survival() reports per-cause cumulative incidence (cif) alongside all-cause survival (survival_all). Recovers the cause-specific rates TVLAMBDA_A = 0.10, TVLAMBDA_B = 0.06.
  • pktte_joint: Joint PK-TTE: a time-to-event endpoint whose hazard depends on the drug concentration, fit jointly with the PK. The [event_model] block’s hazard = H0 * exp(BETA * (central / V)) references the ODE PK state; ferx appends it as a cumulative-hazard ODE state (d/dt(__chz) = hazard) and estimates PK + TTE together by FOCEI, sharing the CL random effect (ferx-core #564). Oral dose on CMT 1, PK observed on CMT 2, event on CMT 3. ferx_fit() and ferx_predict_survival() are supported; simulating an ODE-accumulated hazard is not yet (a later slice adds the event-time root-finder).
  • two_cpt_oral_cov_ode_template: Two-compartment oral PK with covariates written with ode_template two_cpt_oral(...) in [structural_model]: ferx generates the standard disposition ODE (states, micro-constant RHS, and obs_scale = V1) instead of you hand-writing it. Identical predictions to the analytical two_cpt_oral_cov and the hand-ODE two_cpt_oral_cov_ode forms. Re-declaring a d/dt(X) in [odes] overrides only that compartment – the standard way to attach a built-in absorption input such as transit(...). (Requires ferx-core with FeRx-NLME/ferx-core#363.)
  • warfarin_ode_lagtime: One-compartment oral (warfarin) as an ODE model demonstrating the LAGTIME keyword in [individual_parameters]. Assigning to the reserved name LAGTIME delays every dose event for that subject by the individual lag time; no change to the ODE equations is needed. IIV on LAGTIME is log-normal; individual lag times are recovered in fit$individual_estimates. Contrast with the lagtime= argument used in analytical PK solvers (warfarin_additive_eta).
  • emax_pkpd: Simultaneous PK/PD: oral 1-compartment PK plus an effect-compartment Emax PD readout, fit jointly with a SEPARATE residual error model per endpoint via a per-CMT [error_model] block (CMT=2: DV ~ proportional(...) for plasma, CMT=3: DV ~ additive(...) for the PD effect). Demonstrates multi-endpoint fitting; requires gradient = fd.
  • warfarin_derived: One-compartment oral (warfarin) with a [derived] block demonstrating per-row expressions (KE, T_HALF), aggregates (CMAX, TMAX, CMAX_D1), numeric integration (AUC_0_72, AUC_TAU, AUC_DV_72), and an [output] block echoing CL, V, KA. Uses TAFD and TAD as built-in context variables.
  • warfarin_derived_pkpd: One-compartment oral (warfarin) with PD effect and time-above-MEC derived quantities. Demonstrates TAD-gated Cmax and integral(1.0, IPRED > MEC, window=24) for time above minimum effective concentration.
  • two_cpt_oral_derived: Two-compartment oral PK with micro-rate constants and day-specific Cmax computed in [derived]. Demonstrates integral(IPRED, from=0, to=168) and periodic AUC.
  • warfarin_addl: One-compartment oral (warfarin) with ADDL-column dosing. A single EVID=1 row with ADDL=6, II=24 is expanded to seven daily doses at read time; TAD resets at each expanded dose automatically. Demonstrates daily trough accumulation over seven doses and CMIN_TAU using TAD < 1e-10 for floating-point-safe trough detection.
  • warfarin_ode_time: One-compartment oral (warfarin) as an ODE model demonstrating TIME, T, TAFD, and TAD inside [odes] RHS expressions; accumulator compartments for AUC and time-above-threshold.
  • warfarin_data_selection: One-compartment oral (warfarin) demonstrating the [data_selection] block. Observations below a surrogate LLOQ (DV < 1.0 mg/L) are excluded at read time without modifying the CSV, equivalent to NONMEM $DATA IGNORE=. Exclusion counts are reported in fit$exclusions and echoed by print.ferx_fit() and ferx_runlog().
  • adaptive_tdm: State-reactive (adaptive / feedback) dosing: a vancomycin-style TDM trough titration. The dose is not in the data – the model’s [adaptive_dosing] block titrates the next q12h dose to drive the measured (assay-noised) pre-dose trough into a 10-20 mg/L window. Run with [ferx_simulate_adaptive](ferx_simulate_adaptive.qmd) (not ferx_fit); the base subjects are dose-free, so the controller supplies every dose. Returns the concentration trajectories, the realized dose ledger, and the per-decision log (ferx-core epic #391).

Call ferx_example() with no arguments to list all available names. Each example has a matching end-to-end R script installed with the package. List all scripts with:

list.files(system.file("examples", package = "ferx"), pattern = "\.R$")

Open any script directly in RStudio with file.show() or file.edit(), for example:

file.edit(system.file("examples", "ex1_warfarin.R",     package = "ferx"))
file.edit(system.file("examples", "ex_warfarin_dcm.R",  package = "ferx"))

Seealso

Other utilities: [ferx_columns](ferx_columns.qmd)(), [ferx_load_fit](ferx_load_fit.qmd)(), [ferx_save_fit](ferx_save_fit.qmd)()

Concept

utilities

Value

If name is NULL, a character vector of available examples. Otherwise, a list with components:

Examples

ferx_example()                        # list all available example names
ex <- ferx_example("warfarin")
ex$model
ex$data

# List all bundled example scripts:
list.files(system.file("examples", package = "ferx"), pattern = "\\.R$")


# Open a script in RStudio to read or run it:
file.edit(system.file("examples", "ex1_warfarin.R", package = "ferx"))

# Deep Compartment Model (requires nn cargo feature):
dcm <- ferx_example("warfarin_dcm")
fit <- ferx_fit(dcm$model, dcm$data, method = "focei")
fit$neural_networks[[1]]$shape   # NN layer dimensions
file.edit(system.file("examples", "ex_warfarin_dcm.R", package = "ferx"))