Building a Candidate-Run Registry

Why Keep a Candidate-Run Registry?

NLME model development generates more than model code and a final estimate table. A candidate may be fitted repeatedly; a run may fail before returning estimates; and several files may be produced by one execution. Without a consistent way to connect those pieces, a result can become separated from the configuration that produced it. A candidate-run registry provides that connection: it is an organized record of candidate specifications, execution attempts, statuses, estimates, logs, and output files.

The central design decision is to distinguish what was specified from what was executed. A model candidate describes a particular model and its configuration. A run is one attempt to execute that candidate. The same candidate can therefore have multiple runs, for example if an attempt fails and is retried. Treating each attempt as a separate run prevents a retry from silently replacing the history of the first attempt.

The registry is not itself a model specification, an estimation method, or a judgment that a fit is suitable. It makes the relationships among records explicit. The earlier material on versioning data, code, and model specifications provides the basis for recording which versioned inputs a candidate refers to; the registry adds a consistent index for the candidate and its runs.

Separate the Records Before Assigning Identifiers

A useful registry has at least two core record types. A candidate record describes the intended model configuration and points to its specification. A run record describes one execution attempt and points back to exactly one candidate. Associated estimates and files should also be linked to the run that produced or reported them, rather than stored as unlabelled values in a shared folder.

Identifiers should be unique within the registry and stable after assignment. A sequential identifier such as CAND-001 or a generated identifier can work. A readable label such as “two-compartment model” is useful as a description, but it is a poor primary key: the label may be reused, shortened, or revised. Do not encode mutable properties such as status in an identifier. A run that changes from running to failed must keep the same run ID.

A simple file can be sufficient for a small, carefully controlled analysis; a database may be more practical when many people or automated processes update the records. Either way, the structure matters more than the storage technology. Repeated fields such as multiple parameter estimates or several output files should be represented as multiple linked records, not compressed into an ambiguous text cell. The run ID is the link: each estimate and artifact record states which run it belongs to.

Define What a Run Record Must Capture

The run record should answer, at minimum: which candidate was run, when the attempt started, whether it is still active or has ended, and where its associated records and files can be found. It should also record enough execution settings to interpret the attempt, such as the estimation method and configured iteration limit, when those settings are relevant to the analysis. Candidate-level settings belong with the candidate configuration; run-level settings belong with the attempt. Avoid duplicating fields without indicating which record is authoritative.

Use a controlled set of statuses rather than free-form phrases. For example, a workflow may use queued, running, succeeded, failed, and cancelled. Define each term locally and apply it consistently. “Succeeded” should mean the execution reached the workflow’s defined completion condition; it does not mean that the model is scientifically adequate, that all estimates are trustworthy, or that an independent review has approved the output.

When status history matters, retain events rather than only the latest value. For instance, a run can have a queued event followed by a running event and then a failed event. The current status can be displayed as failed, while the event records preserve how it reached that state. If an append-only event log is not practical, at least retain the final status and its time, and avoid overwriting the only record of a prior terminal attempt when creating a retry.

Link Estimates and Files Without Losing Context

A parameter estimate is meaningful only with its parameter name, the run that returned it, and its interpretation. Store the value with units where units apply and state its scale or parameterization where that affects interpretation. For example, a clearance estimate reported in litres per hour is not interchangeable as a displayed value with a log-clearance estimate. Preserve enough context to tell which was recorded. If an estimate is unavailable, do not substitute zero: zero is a numerical value, not a missing-result code.

Artifacts should be recorded as separate entries when a run has multiple files. A useful artifact record identifies the run, the file’s role (for example, estimation log or parameter table), and its location. A file name alone may not identify a file uniquely, particularly if different run folders reuse the same name. Use a location that resolves unambiguously within the analysis environment and retain a clear indication if a file is missing or no longer available. A registry entry points to a file; it does not guarantee that the file is intact or that its contents are correct.

Build and Check the Registry as a Linked System

The registry is reliable only if its links and status rules are coherent. A small set of checks can catch structural problems before the records are used to summarize model-development work. These checks concern the registry’s organization; they do not establish that the model has converged or that its estimates are appropriate.

The logic for separating candidate and run IDs is straightforward. If the candidate itself is the only identifier, a retry must either reuse the same record and overwrite its outcome, or create a second candidate even though the intended configuration is unchanged. The first choice erases an execution attempt; the second confuses a model specification with an execution. With separate IDs, the candidate remains one specification and each attempt is separately identifiable. This is why the candidate-to-run relationship is one-to-many, while each run refers to one candidate.

Diagnostics, Alternatives, and Limits

Common warning signs include duplicate IDs, runs with no candidate link, estimates with no run link, output paths that do not resolve, and records marked succeeded despite having no expected completion output. Such findings call for resolving or flagging the inconsistency, not guessing which record was intended. A missing log should be recorded as missing; it should not be treated as evidence that the execution succeeded or failed. Similarly, a successful execution status is not a substitute for reviewing estimation output.

A spreadsheet is an accessible alternative to a database and can work for a small registry if identifiers, allowed statuses, and linked tables are maintained consistently. A database can enforce uniqueness and link constraints more directly, which is useful as the number of records or contributors grows. A collection of filenames and folders alone is weaker: filenames can be changed or reused, and they do not inherently record status transitions or connect estimates to a candidate. Whichever storage format is chosen, the same concepts—separate records, stable IDs, explicit links, and defined statuses—are needed.

A registry also has limits. It can show what was recorded and where files were expected to be; it cannot prove that a configuration reference was implemented correctly, that an output file is valid, or that a fitting procedure met its scientific objectives. Those require checks beyond registry structure. The registry is a traceable index for model-development work, not a certificate of model validity.

Common Mistakes

• Reusing a run ID for a retry. This overwrites or blurs execution history. Assign a new run ID for every attempt and link it to the same candidate when appropriate.
• Using the model label as the only identifier. Labels can be edited or repeated. Keep a stable candidate ID and store the label as a description.
• Recording only a final status. This may conceal whether an attempt was retried or how it ended. Preserve relevant status events or, at minimum, retain each attempt as its own run record.
• Treating “succeeded” as “acceptable.” Execution completion is a computational status, not a scientific conclusion about fit quality.
• Saving estimates without units or run links. A bare number can be misinterpreted or assigned to the wrong attempt. Record its parameter, interpretation, and run ID.