CLI Reference

The ferx command-line tool runs population PK estimation from model files and data.

Usage

ferx <model.ferx> --data <data.csv> [--output <run.fitrx>] [--include-data] [--inits-from-nca[=METHOD]] [--output-format yaml|json|both]
ferx <model.ferx> --simulate          [--output <run.fitrx>]
ferx check <model.ferx> [--data <data.csv>] [--json]
ferx summary <run.fitrx> [<run2.fitrx> ...]
ferx --help                    # or -h; also: ferx check --help, ferx summary --help

Commands

Fit with Data

ferx model.ferx --data data.csv

Parses the model file, reads the data, and runs the estimation method specified in [fit_options] (defaults to FOCEI).

Simulate and Fit

ferx model.ferx --simulate

Parses the model file, generates simulated data from the [simulation] block, and fits the model to the simulated data. Requires a [simulation] block in the model file.

Validate without Fitting (`check`)

ferx check model.ferx                  # parse + structural validation
ferx check model.ferx --data data.csv  # also run data-dependent checks
ferx check model.ferx --data data.csv --json

Runs the parser and every validation step that normally happens at the start of a fit — without fitting — then reports the findings. This is a fast author → diagnose → fix loop, especially useful for tooling and coding agents that author model files programmatically.

Without --data, parse / structural and model–option compatibility checks run (no data is read) — e.g. an SDE model paired with SAEM, or optimizer = trust_region on an IOV model.
With --data, the dataset is read and the data-dependent checks run too: referenced covariates present, per-CMT scaling / error-model coverage, steady-state dosing well-formed, and non-negative typical-value lag time.
--json emits a structured check report to stdout instead of the human-readable summary.

Human output lists one diagnostic per line as severity[CODE] block:line: message, with an indented help: line for any suggestion, then a one-line summary:

error[E_MISSING_COVARIATE]: Model references covariate(s) not found in data (case-sensitive): WGT. Available covariate columns: (none).
    help: available covariate columns: (none)
invalid: mymodel — 1 error(s), 0 warning(s)

The exit code is 0 when no errors are found (warnings alone still exit 0), 1 when any error is found, and 2 on a usage error. See the check report reference for the JSON schema and the full error-code table.

Summarize a Saved Fit (`summary`)

ferx summary run1.fitrx

Loads a saved .fitrx bundle and prints a concise, psn::sumo-style summary of the run to stdout — no re-fitting, no data required. Handy for reviewing an old run, diffing two fits, or piping into a report. The summary covers:

Run status — estimation method (or chain), convergence, iterations, and the subject / observation / parameter counts.
Objective function — OFV, AIC, BIC.
Parameter estimates — the THETA table with SE and %RSE, OMEGA variances with CV% and off-diagonal correlations, and SIGMA (with CV% for the proportional component). [FIX]-flagged parameters show --- for SE.
Diagnostics — covariance status, condition number, and η / ε shrinkage.
Run info — wall time, ferx version, and any fit warnings.

============================================================
ferx run summary — warfarin
============================================================
Method:     FOCEI
Converged:  YES
Iterations: 28
Subjects: 32   Observations: 251   Parameters: 7

--- Objective Function ---
  OFV:  -280.1838
  ...

The exit code is 0 on success, 1 if the bundle cannot be loaded, and 2 on a usage error (missing path).

Compare Multiple Runs

Pass two or more bundles to compare them side by side. Instead of the single-run report above, summary prints a Markdown table — method, convergence, OFV / AIC / BIC, ΔOFV (relative to the first run), runtime, and the subject / observation / parameter counts, followed by THETA (with %RSE), OMEGA, and SIGMA estimate tables. Each column is labelled with the bundle’s file stem, and a — marks a parameter absent from a run. Handy for pasting into a report or a PR.

ferx summary run1.fitrx run2.fitrx run3.fitrx

| Run | run1 | run2 | run3 |
| --- | --- | --- | --- |
| Model | warfarin | warfarin | warfarin |
| Method | FOCE | FOCEI | SAEM → IMP |
| Converged | yes | yes | yes |
| OFV | -280.3639 | -281.0102 | -280.9998 |
| ΔOFV | +0.0000 | -0.6463 | -0.6359 |
| ... | ... | ... | ... |

**THETA**

| Parameter | run1 | run2 | run3 |
| --- | --- | --- | --- |
| TVCL | 0.1330 (5.0%) | 0.1332 (4.9%) | 0.1331 (5.1%) |
| ... | ... | ... | ... |

Output Files

Two files are always generated, named after the model file:

File	Contents
`{model}-sdtab.csv`	Per-observation diagnostics
`{model}-fit.yaml`	Parameter estimates, standard errors, an `estimation:` block (wall time, thread count), an `environment:` block (OS, arch, Docker, username, ferx version), and (when the covariance step ran) a `covariance_matrix:` block containing the full optimizer-space parameter covariance matrix

See Output Files for detailed format descriptions.

Portable Fit Bundle (`--output`)

Pass --output run.fitrx to additionally write a portable .fitrx bundle — a zip of JSON and CSV designed to be read from Rust, R, Python, or Julia. Use --include-data to embed the input NONMEM CSV inside the bundle (off by default).

ferx model.ferx --data data.csv --output run1.fitrx --include-data

Estimates format (`--output-format`)

The human-readable estimates file defaults to YAML ({model}-fit.yaml). Pass --output-format to control it:

Value	Writes
`yaml` (default)	`{model}-fit.yaml` — curated, human-readable
`json`	`{model}-fit.json` — the complete `FitResult`, machine-readable
`both`	both files

ferx model.ferx --data data.csv --output-format json

The JSON is the full fit under a versioned schema — intended for scripts, the R wrapper, or an agentic model-development loop. It is unrelated to the --output .fitrx bundle above (which packages a whole run for archival/interchange). See Output Files for the schema.

NCA-based starting values (`--inits-from-nca`)

Pass --inits-from-nca to derive starting values from the data via non-compartmental analysis before fitting, overriding the model file’s defaults. The flag overrides the inits_from_nca [fit_options] key for this run. A bare --inits-from-nca uses the nca_sweep strategy; pass an explicit method to pick another:

ferx model.ferx --data data.csv --inits-from-nca           # = nca_sweep
ferx model.ferx --data data.csv --inits-from-nca=nca       # NCA only (fastest)
ferx model.ferx --data data.csv --inits-from-nca=nca_ebe   # EBE-refined sweep

See NCA-based starting values for what each strategy does.

See the .fitrx format reference for the full schema.

Console Output

Progress

The estimation progress is printed to stderr, including: - Model and data summary (subjects, observations, parameters) - Optimizer iterations with OFV values (FOCE) or condNLL values (SAEM) - Covariance step status - Final parameter table

Result Summary

A brief summary is printed to stdout:

Fit completed!
OFV: -280.1838
Elapsed: 0.496s
  TVCL = 0.132735
  TVV = 7.694842
  TVKA = 0.757498

Exit Codes

Code	Meaning
0	Success (for `check`: no errors found; also returned by `-h`/`--help`, which prints usage to stdout)
1	Error (parse failure, data error, convergence failure; for `check`: errors found; for `summary`: bundle failed to load)
2	Usage error for `check` / `summary` (e.g. missing model or bundle path)

-h/--help is recognized as the first argument (ferx --help) and as the argument right after check/summary (ferx check --help, ferx summary --help); it prints usage to stdout and exits 0 (usage-error paths print the same text to stderr and exit 1/2).

Examples

# One-compartment oral warfarin model
ferx examples/warfarin.ferx --data data/warfarin.csv

# Two-compartment IV with FOCE
ferx examples/two_cpt_iv.ferx --data data/two_cpt_iv.csv

# SAEM estimation
ferx examples/warfarin_saem.ferx --data data/warfarin.csv

# Simulation-estimation study
ferx examples/warfarin.ferx --simulate

Building

# Build the ferx binary
cargo build --release

# Run directly via cargo
cargo run --release --bin ferx -- model.ferx --data data.csv