Why Run Status Needs a Definition
A run directory can contain a log, parameter table, and objective-function value while the estimation process has failed or stopped early. Conversely, a process can finish normally while reporting that the model did not converge. These are different facts. A reliable run record makes both visible: what happened during execution and what result the estimation produced.
This distinction matters in pharmacometric work because run records support later review and reproducibility. A reviewer should be able to tell whether a result came from a completed execution, whether estimation reported convergence, and which important values were actually available. Files are evidence to inspect, not a status definition by themselves.
A Consistent Status Vocabulary
Choose a small, documented vocabulary and use it consistently across runs. One workable set is not_started, running, completed, failed, interrupted, and unknown. The first two describe nonterminal states; the next three describe different terminal events; unknown means the available record does not support a defensible classification. The set should be agreed within a workflow rather than varied informally from run to run.
| Status | Meaning | Typical supporting evidence |
|---|---|---|
| not_started | Execution has not begun. | A registered run record with no start event. |
| running | Execution has begun and no terminal event is recorded. | A start event and evidence of an active process or job. |
| completed | Execution ended through the expected normal completion path. | Normal process exit and expected completion evidence, assessed under the workflow’s rules. |
| failed | Execution ended unsuccessfully because of an error, such as a fatal software error or an unsuccessful process exit. | An error or abort record, or other direct evidence of unsuccessful termination. |
| interrupted | Execution was stopped before normal completion by an external or deliberate stop event. | A scheduler termination, documented user stop, or other evidence of interruption. |
| unknown | Evidence is missing or conflicting, so no terminal classification is justified. | Incomplete logs, absent termination evidence, or inconsistent records. |
Status labels describe what can be established, not what an analyst hopes happened. For example, do not infer interrupted simply because a log ends suddenly: the process may have failed, the log may be incomplete, or evidence may have been lost. Record unknown until the available evidence supports a more specific classification.
Assigning Status From Evidence
A status rule should specify which evidence is checked and how conflicts are handled. Useful evidence can include process exit information, scheduler records, the final log message, software-specific termination indicators, and checks that expected outputs are readable. The workflow should identify authoritative sources where possible and preserve the evidence used to classify the run. The mere existence of an output file is insufficient: it may be stale, partial, or written before an error.
A practical assignment sequence is to establish whether execution started, determine whether a terminal event is documented, and then distinguish normal completion from failure or interruption. If the evidence cannot resolve the distinction, retain an unknown status and explain why. This conservative rule prevents an incomplete record from becoming a false claim of success.
Associate evidence with the intended run identifier and its recorded model version and inputs; do not classify a directory by its name alone.
Record whether execution started and, if available, its start time, end time, process exit information, and scheduler event.
Use the documented evidence rules to choose a status. If the evidence is absent or contradictory, use unknown and record the limitation.
Capture convergence reporting and available numerical results, including explicit reasons when a value is unavailable.
The logic behind separating these fields is straightforward. Consider two independent questions: whether the process reached its expected end, and whether estimation reported a desired result. Since either answer can vary while the other stays fixed, one status field cannot represent both without losing information. For example, a normal process exit can accompany a nonconvergence report, while an unexpected termination can leave some intermediate estimates behind. Separate fields preserve these distinctions.
What to Record as an Outcome
The exact outcome fields depend on the estimation software and the purpose of the run, but a useful record makes values interpretable and their provenance clear. Capture the field name, value, units or scale where relevant, and source (for example, a named report or log section). Common fields include:
- Estimation result: a normalized label such as converged, not_converged, or not_assessed, alongside the software’s own diagnostic wording when available.
- Objective result: the objective-function value, its reported name or definition, and any scale or convention needed to interpret it. Do not store a bare number with no label.
- Parameter results: estimates and units, plus standard errors or other uncertainty summaries when reported. Mark unreported values as unavailable rather than filling them with zero.
- Warnings and termination details: relevant warning text, the final reported iteration when available, and software exit information.
- Timing and evidence: start and end timestamps with a stated time zone, elapsed time with units, and references to the log or other supporting artifacts.
A missing field needs an explicit meaning. Distinguish not produced (the process did not generate it), not reported (the software did not provide it), not extracted (it may exist but was not captured), and not applicable. A blank cell or numeric zero does not communicate which case applies. Preserve partial results when they are useful, but label them as partial and do not present them as final estimates.
Worked Example: Normal Exit With No Convergence
Suppose a hypothetical estimation run has run ID PKM-042. The process exits with code 0 at 14:32, and the log contains the software’s normal termination message. The estimation report says “maximum iterations reached; convergence not achieved.” The objective-function value is reported as 1,248.6, and the final parameter table is readable.
Status assignment. Under a rule that treats the normal exit and expected termination message as evidence of normal execution completion, record completed. The convergence statement does not change that execution status.
Outcome assignment. Record estimation result not_converged, preserve the diagnostic wording, and record objective-function name and value as reported (for example, “objective function,” 1,248.6). Capture the parameter values as available results, clearly identifying them as estimates from a run that did not report convergence.
The record does not say that the model is acceptable or that the estimates are suitable for inference. It accurately separates normal process completion from the unsuccessful convergence outcome.
Worked Example: Interrupted Run With Partial Files
In a hypothetical second run, the scheduler records a termination request at 09:18. The process began at 09:00, no normal termination message appears, and a parameter file was written at 09:12. The file contains three of five requested parameter estimates. The scheduler record identifies the stop as a user cancellation.
The elapsed time is \(09{:}18-09{:}00=18\) minutes. Record status interrupted, start and end times, the scheduler’s cancellation evidence, and elapsed time as 18 min. Do not call the run completed because a parameter file exists.
For the outcome, record that the estimation result is not_assessed or otherwise unavailable under the workflow’s defined labels, and mark the parameter table as partial. The three reported values may be retained with a partial-results flag; the two absent values should have a reason such as “not produced before interruption.” This record preserves information without implying that the partial table is a final estimation result.
Worked Example: Output Present but Status Unknown
A hypothetical archived run contains a log and a file named final_estimates.csv. The log ends during iteration 74, the scheduler history is unavailable, and there is no recorded exit code or normal termination message. The CSV contains five numerical entries.
The filename does not establish that the estimates are final, and the incomplete log does not prove that execution was interrupted rather than failed. Assign status unknown. Record the missing evidence and preserve the files as observed, without asserting a successful completion.
The five values can be recorded as available file contents only if their source and uncertain status are explicit. Do not label them as verified final estimates. This is not a failure of record keeping: “unknown, because termination evidence is unavailable” is more accurate and reproducible than a guessed terminal status.
Validation, Diagnostics, and Common Pitfalls
A run record is more dependable when basic consistency checks are applied before it is used. Check that a terminal status has corresponding termination evidence, that a running run has a recorded start event, and that timestamps are ordered. Where both start and end times exist, elapsed time should agree with their difference to the recorded precision. Confirm that each numerical outcome has a field name and required units or scale, and that missing values have reason codes. Keep the original software wording alongside any normalized label so a later reviewer can see what the normalization represents.
Conflicts should be visible rather than silently reconciled. A zero exit code alongside a fatal error message may reflect a software-specific convention, a wrapper issue, or an incomplete record. Apply documented software-specific rules and preserve both pieces of evidence; if those rules do not resolve the conflict, classify the status as unknown. A diagnostic that is meaningful for one estimation program may not map cleanly to another program’s terminology.
There are limits to what a status record can establish. A completed status documents an execution event; it is not a diagnostic guarantee about model adequacy, data support, or scientific validity. A reported convergence label is also software-dependent and does not substitute for reviewing diagnostics. This tutorial’s status and outcome fields make the record interpretable; they do not replace the separate evaluation of model results.
A useful alternative to a single combined label such as “successful” is a two-part record: one field for execution status and another for estimation outcome. A combined label is compact, but can hide cases such as normal completion without convergence or interruption after partial output. The separate-field approach is more explicit and supports precise review. The trade-off is that the vocabulary and rules must be documented and applied consistently.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A process exits normally and its report says “convergence not achieved.” Which execution status and estimation outcome should be recorded?
- A parameter file exists, but there is no exit code, completion message, or scheduler history. What status is justified, and why?
- A scheduler confirms that a run was stopped by a user before normal completion. The log contains some estimates. How should the status and partial results be represented?
- A run starts at 10:05 and ends at 10:47. What elapsed time should be recorded? What additional information makes the timestamps interpretable?
- Why should an unavailable standard error not be entered as zero?
Solutions. (1) Record execution status completed if the documented normal-exit checks pass, and estimation outcome not_converged; the two fields answer different questions. (2) Record unknown, because file presence does not establish how execution ended. Note the missing termination evidence. (3) Record interrupted, preserve the estimates as partial if their source is clear, and mark unproduced values with an explicit reason; do not call the table final. (4) Record \(10{:}47-10{:}05=42\) minutes. Include the date and time zone so the timestamps can be interpreted and reconciled. (5) Zero is a numerical result, whereas an unavailable standard error was not reported or produced. Record the appropriate missing-value reason rather than implying a value of zero.