Reading a NONMEM Control Stream as a Workflow
A NONMEM control stream is more than a list of commands: it specifies how a dataset is read, how a model uses those records, what estimation procedure is requested, and which results are written out. Reading it in that order makes it easier to check whether a run actually answers the intended modeling question. It also helps distinguish a problem in the data from one in the model, estimation, or output configuration.
Control records begin with a dollar sign, such as $DATA or $ESTIMATION. A record can contain settings on the same line or continue over subsequent lines, depending on the record and syntax. The sections work together, but each has a distinct role: a table request cannot repair a wrongly mapped input column, and an estimation setting does not define the structural model.
Sections That Connect Data, Model, Estimation, and Output
The following records are common in a population pharmacokinetic estimation workflow. Not every run needs every record, and some records have options not shown here.
| Record or section | Main role | Questions to check |
|---|---|---|
| $PROBLEM | Provides a descriptive label for the run. | Does the label identify the analysis clearly? |
| $INPUT and $DATA | Map dataset columns to NONMEM variables and identify the data file and applicable reading options. | Do the names and order match the actual file? |
| $SUBROUTINES, $PK, $ERROR | Specify the differential-equation routine, individual parameter calculations, and observation model. | Do the chosen routine and code represent the intended model? |
| $THETA, $OMEGA, $SIGMA | Provide initial values and bounds for fixed effects, and specify variability and residual-error parameters. | Are values and constraints appropriate for the parameters' meanings? |
| $ESTIMATION and $COVARIANCE | Request parameter estimation and, when requested and successfully computed, covariance-based uncertainty results. | Did estimation terminate appropriately, and was covariance estimation successful? |
| $TABLE | Requests selected variables to be written for records or individuals. | Does the table contain enough identifiers and diagnostics to interpret each row? |
These records are interpreted together. $INPUT names the fields NONMEM will use; $DATA points to the file. Model code refers to those mapped names. The parameter records supply starting values and variability specifications, while $ESTIMATION requests the fitting procedure. Finally, a $TABLE record requests selected values for inspection or downstream work. The listing file, commonly identified by an extension such as .lst, reports run information and results; other files and their names depend on the run number, options, and environment.
Worked Example: Mapping Dose and Observation Records
Worked Example: Mapping Dose and Observation Records
Suppose a hypothetical dataset contains records for a one-compartment IV-bolus model. The fields, in order, are subject identifier, time in hours, dose amount in milligrams, observed concentration in milligrams per liter, event identifier, and missing-dependent-variable indicator. A small excerpt is:
A corresponding mapping and file declaration could be:
First row: subject 1 receives an amount of 100 mg at time 0. The event identifier indicates a dose record, and MDV is 1, so this row is not treated as an observed dependent-variable value for the likelihood. The recorded 0.0 in DV is a placeholder here, not a concentration measurement.
Second and third rows: both are observation records because EVID is 0. MDV is also 0, so DV contains observed concentrations: 4.2 mg/L at 1 hour and 2.8 mg/L at 2 hours. The dose and observation records are different kinds of records even though they belong to the same subject.
For this interpretation to hold, the dataset columns must really appear in the declared order, times and doses must use the stated units, and event and missing-data codes must follow the intended NONMEM conventions. A column shift can produce syntactically readable data that nevertheless represent the wrong events or measurements.
Worked Example: Following the Model and Parameter Records
Worked Example: Following the Model and Parameter Records
Consider this abbreviated, hypothetical control stream. It is intended to illustrate how sections connect, not to prescribe a validated analysis for any real dataset.
Here $SUBROUTINES ADVAN1 TRANS2 selects a built-in one-compartment IV-bolus routine and a clearance-and-volume parameterization. The $PK block defines individual clearance as typical clearance multiplied by an exponential individual effect, and defines volume from its typical value. S1=V specifies the scaling used to report concentration from the compartment amount. This example assumes dose and concentration units are consistent with clearance in volume per hour and volume in volume units.
The two entries in $THETA provide initial values of 5 for clearance and 20 for volume, with lower bounds of 0. The $OMEGA value 0.09 specifies the variance of ETA(1), and $SIGMA value 0.04 specifies the variance of EPS(1). Thus their standard deviations are \(\sqrt{0.09}=0.3\) and \(\sqrt{0.04}=0.2\), respectively. The observation equation uses a proportional residual-error form. These values are illustrative starting specifications, not results or evidence that the model is suitable.
The estimation record requests METHOD=1 with INTERACTION and permits up to 999 evaluations; PRINT controls reporting frequency. The covariance record requests covariance-based results after estimation. The table record requests identifiers, event information, the observed value, and two user-defined quantities. In this code, IPRED is the model prediction F and IRES is DV minus that prediction. IRES is only interpretable as an observation residual on records with an observed DV; dose records are not observations for this purpose.
Worked Example: Tracing One Prediction into the Output
Worked Example: Tracing One Prediction into the Output
Use the record at time 2 hours from the hypothetical data above. For a transparent hand calculation, suppose the parameter values are fixed at CL = 5 L/h and V = 20 L, and ETA(1) = 0. These assumed values are for tracing the computation; they are not claimed to be estimates from the data.
For an IV bolus in a one-compartment model, the concentration at time \(t\) after a dose \(D\) is \(D/V\) multiplied by exponential elimination. The elimination rate is \(CL/V\). Therefore, for this record:
The observed concentration is 2.8 mg/L, so the defined individual residual is:
The negative sign means the observation is below this prediction by about 0.233 mg/L. A requested table row for this observation could therefore contain ID 1, TIME 2, DV 2.8, IPRED about 3.033, and IRES about -0.233, along with the requested event fields. An actual run's values would depend on its estimated parameters and implementation details; these numbers follow only from the assumed values stated here.
Why the Section Boundaries Matter
A useful way to read a control stream is to trace one value through the workflow: an input field is mapped by $INPUT, a record is read from the file named under $DATA, the model uses event information and parameter definitions to calculate a prediction, estimation adjusts unknown parameters, and $TABLE requests selected results. The run listing and other output files provide evidence about what happened, but the files should be interpreted in light of the control stream that generated them.
Compare $INPUT with the physical dataset columns, then verify the file path and data-reading options under $DATA.
Check subject identifiers, times, event codes, missing-value indicators, and units before interpreting dose or observation rows.
Follow the selected subroutine and model code, including the parameter mappings and observation model.
Review estimation status and reported estimates, then inspect requested tables and other available outputs in context.
A successful-looking table does not establish that the model was correctly specified or that estimation converged appropriately. Conversely, a failed covariance step does not by itself mean that the data were unreadable or that no parameter estimates were obtained. Separate the run into stages when diagnosing it.
Diagnostics, Failure Modes, and Alternatives
Start with data integrity. Confirm that the declared columns match the file, that each row is assigned the intended subject and event type, and that records are ordered and coded consistently with the model. Check that missing DV values are marked appropriately and that units agree across dose, time, concentration, clearance, and volume. Unexpected predictions or residual patterns may be symptoms of an earlier mapping or event problem rather than a problem with the estimation algorithm.
Next, inspect the model and estimation record. Confirm that the subroutine matches the intended structural model, that all referenced THETA, ETA, and EPS quantities are defined, and that bounds and initial values are sensible. Examine the listing for termination status, warnings, parameter estimates, and objective-function information. If covariance results were requested, verify whether that calculation completed; do not treat the mere presence of a covariance record as proof that standard errors are reliable.
Finally, inspect the table itself. Confirm its header, units, record types, and whether values appear on the rows you intend to analyze. A table containing a value on a dose row does not make that row an observed concentration. If needed, request additional fields such as EVID or MDV to distinguish records and make the table easier to audit.
The control stream is the core NONMEM specification, but it is not the only way a run can be managed. A workflow may use scripts or run-management tools to create files, submit jobs, track status, or collect results. Those tools can improve reproducibility and organization, but they do not change the meaning of the NONMEM records or substitute for checking the input, model, and run outputs. The main limitation of reading the stream alone is that it cannot prove the data file used at execution time was the intended file or that a requested result was successfully produced; inspect run records and generated outputs as well.
Common Mistake
Correction: A table can include dose records as well as observation records, and the requested columns do not establish that estimation succeeded. Use fields such as EVID and MDV to identify record types, and check the listing and relevant output files for run status and results before interpreting the table.
Check Your Understanding
Answer each question, then compare your reasoning with the brief solutions.
- In the example mapping, what does MDV=1 communicate on the dose row, and why is its DV value not interpreted as an observation?
- Which control-stream record identifies the data file, and which one maps its columns to NONMEM variables?
- If $SIGMA is 0.04, what is the residual-error standard deviation, and what does 0.04 represent?
- At the 2-hour record, explain what a negative IRES means under the definition used in the example.
- Name two checks to perform if a table contains unexpected values or rows.
Solutions. (1) MDV=1 marks the dependent-variable value as missing for the likelihood; the dose row is an event record, not a concentration observation. (2) $DATA identifies the file, while $INPUT maps its fields. (3) The standard deviation is \(\sqrt{0.04}=0.2\); 0.04 is the EPS variance. (4) Since IRES=DV-IPRED, a negative value means the observed concentration is below the prediction. (5) Check the column mapping and record codes, including EVID and MDV; also verify units and inspect the listing for estimation or data-reading problems.