Data Format

FeRx reads data in NONMEM-compatible CSV format. This is the standard format used across population PK tools.

Required Columns

ColumnTypeDescription
IDstring/numericSubject identifier
TIMEnumericTime relative to first dose
DVnumericDependent variable (observed concentration)

Optional Standard Columns

ColumnTypeDefaultDescription
EVIDinteger0Event ID: 0 = observation, 1 = dose, 4 = reset + dose
AMTnumeric0Dose amount (only for EVID=1 or EVID=4)
CMTinteger1Compartment number (1-indexed)
RATEnumeric0Infusion rate. 0 = bolus dose
MDVinteger0Missing DV flag. 1 = DV should be ignored
IInumeric0Interdose interval for repeated dosing
SSinteger0Steady-state flag. 1 = assume steady state
CENSinteger0Censoring flag. 1 = observation is below LLOQ; DV carries the LLOQ value. Paired with bloq_method = m3 in [fit_options] to enable likelihood-based handling — see BLOQ example.

Occasion Column (IOV)

When using Inter-Occasion Variability (IOV), add an occasion-index column to the dataset and specify its name with iov_column in [fit_options]. The column:

  • Contains integer occasion indices (e.g. 1, 2, 3…) — one per row
  • Applies to both dose rows and observation rows
  • Is excluded from covariate auto-detection

Example dataset with OCC column:

ID,TIME,DV,EVID,AMT,CMT,MDV,OCC
1,0,.,1,100,1,1,1
1,1,9.5,0,.,.,0,1
1,2,7.3,0,.,.,0,1
1,24,.,1,100,1,1,2
1,25,10.1,0,.,.,0,2
1,26,8.2,0,.,.,0,2

The occasion index can be any positive integer; they do not need to start at 1 or be consecutive, but a different number means a different occasion with its own kappa EBE.

See IOV documentation for full details.

Covariate Columns

Any column not in the standard set above is automatically treated as a covariate. Covariate values are:

  • Time-constant: The first non-missing value for each subject is used
  • Time-varying: If values change over time for a subject, Last Observation Carried Forward (LOCF) is applied per event (NONMEM-equivalent: [individual_parameters] is re-evaluated at each dose and observation row using that row's covariate values)

Covariate names in the data file are matched case-insensitively to names used in [individual_parameters] expressions.

Time-varying covariate scope

Time-varying covariates are supported for all analytical structural models and ODE-defined models:

  • 1-compartment IV bolus (one_cpt_iv_bolus)
  • 1-compartment infusion (one_cpt_infusion)
  • 1-compartment oral (one_cpt_oral)
  • 2-compartment IV bolus (two_cpt_iv_bolus)
  • 2-compartment infusion (two_cpt_infusion)
  • 2-compartment oral (two_cpt_oral)
  • 3-compartment IV bolus (three_cpt_iv_bolus)
  • 3-compartment infusion (three_cpt_infusion)
  • 3-compartment oral (three_cpt_oral)
  • All ODE-defined models (via [odes])

For oral models, the bolus dose into compartment 1 is interpreted as the depot (NONMEM ADVAN2/ADVAN4/ADVAN12 convention) and observation read-out reads the central compartment.

The autodiff (Enzyme) gradient fast path is also event-driven for all analytical models — TV-cov subjects keep AD-accelerated gradients and an AD-accelerated H-matrix Jacobian (forward-mode), so neither the inner-loop gradient nor the per-iteration Jacobian falls back to finite-differences.

Infusion routing on the event-driven path:

  • IV models: central infusion (cmt=1) for all 1/2/3-cpt; peripheral infusion for 2-cpt (cmt=2) and 3-cpt (cmt=2 → periph1, cmt=3 → periph2). Steady-state amounts per channel are computed by linear superposition over the channels.
  • Oral models: central infusion (cmt=2) is supported; peripheral infusion is rare clinically and still panics with a clear message (tracked as a follow-up).

Event Types (EVID)

EVIDMeaning
0Observation record. DV is used for estimation.
1Dosing record. AMT is administered to compartment CMT.
2Other event (typically a covariate-change marker). The compartment state is unchanged but the rate matrix is refreshed from this row's covariate values — matching NONMEM's $PK runs at every record semantic. Only meaningful when at least one covariate is time-varying; for time-constant data EVID=2 rows are skipped (would be no-ops).
4Reset and dose. All compartment amounts are reset to zero before dosing.

Example Dataset

ID,TIME,DV,EVID,AMT,CMT,RATE,MDV,WT,CRCL
1,0,.,1,100,1,0,1,70,95
1,0.5,9.49,0,.,.,.,0,70,95
1,1,14.42,0,.,.,.,0,70,95
1,2,17.56,0,.,.,.,0,70,95
1,4,15.23,0,.,.,.,0,70,95
1,8,10.15,0,.,.,.,0,70,95
2,0,.,1,150,1,0,1,85,110
2,0.5,14.2,0,.,.,.,0,85,110
2,1,21.3,0,.,.,.,0,85,110

Key points:

  • Dose records (EVID=1) have MDV=1 and DV=. (missing)
  • Observation records (EVID=0) have MDV=0 and a valid DV
  • Covariates (WT, CRCL) are included as extra columns
  • Missing values can be represented as . or left empty

Infusion Doses

For IV infusions, set RATE to the infusion rate (amount per time unit):

ID,TIME,DV,EVID,AMT,CMT,RATE,MDV
1,0,.,1,500,1,50,1

This administers 500 units at a rate of 50 units/hour (duration = 10 hours).

Steady-State Dosing

For steady-state simulations, set SS=1 and II to the dosing interval:

ID,TIME,DV,EVID,AMT,CMT,SS,II,MDV
1,0,.,1,100,1,1,12,1
1,0.5,25.3,0,.,.,.,.,0

This assumes the subject has reached steady state with 100 units every 12 hours before the observation at TIME=0.5.

Multiple Doses

Multiple doses are supported as separate rows:

ID,TIME,DV,EVID,AMT,CMT,MDV
1,0,.,1,100,1,1
1,0.5,9.49,0,.,.,0
1,12,.,1,100,1,1
1,12.5,15.2,0,.,.,0
1,24,.,1,100,1,1
1,24.5,18.1,0,.,.,0

Column Name Case

Column names are case-insensitive. ID, Id, and id are all recognized. Covariate columns preserve their case as declared in the CSV header.