Managing Candidate Model Versions

Why Candidate Versions Need Their Own Records

A model-development project often has several plausible candidates at once: one may use a different absorption model, another may add a covariate, and a third may retain the same scientific specification while correcting a file path. If these states are identified only by informal names such as “final,” “new” or “best,” the team cannot reliably tell which model was intended for a particular analysis. The problem is not solved by recording only when a computational run occurred. A candidate is a defined model state; a run is an attempt to execute that state under a particular set of conditions.

Managing candidate versions means assigning each distinct model state an explicit, stable identifier and recording what changed from its parent. The record should allow a reviewer to answer, without relying on memory: What is this candidate? Which candidate did it derive from? Was the change scientific, operational, or related to the analysis inputs? Which exact model artifact does the identifier name?

The earlier material on model version lineage establishes the value of recording relationships among model artifacts. Candidate management applies that idea to an active set of alternatives: each candidate receives an explicit version label, and every new revision has a traceable relationship to its predecessor or parent. An identifier should never be reassigned to a different state, even if the old state is no longer used.

A Practical Identity and Change-Record Rule

Use a readable identifier for people and a fingerprint or checksum of the relevant artifact for integrity checking. The label provides a stable handle; the fingerprint helps detect whether the files associated with that handle have changed. A checksum alone is usually a poor working label because it is difficult to read and does not explain the candidate’s place in the model-development sequence. Conversely, a descriptive label without an immutable artifact check can silently continue to name altered files.

A simple scheme can combine a candidate family name with a monotonically increasing revision, such as PK-A-v001 or PK-A-v002. When a candidate branches into distinct alternatives, give each branch its own family or branch label and record its parent. The names need not encode every scientific detail: the change record is where the details belong. Avoid using labels such as “final” as identifiers because the meaning of “final” changes as work continues.

A concise change record is structured rather than a free-form note. It should include the version identifier, parent identifier (or “initial candidate”), date or revision time, change class, a brief description, the affected model component or artifact, and a reference to the exact stored artifact or its checksum. A short rationale can explain why the change was proposed. Keep the record concise enough to scan, but specific enough that “changed PK model” is not the only explanation.

The classification is about the effect of an edit, not the person who made it or the file in which it appears. A one-line change can alter the scientific model, while a larger edit can be operational if it only reorganizes output. Changes to analysis inputs are called out separately because they can change the basis of an analysis even when the model code is unchanged. Do not label such a change “operational” merely because it was implemented in a data-processing script.

Why Immutable Identifiers Prevent Ambiguity

Consider two files both called “candidate-final.” If the second overwrites the first, the name no longer tells a reviewer which specification was used. Adding a date to a filename may reduce the chance of collision, but it still does not explicitly say whether the model changed, which earlier candidate it came from, or whether the contents were later edited. A reliable scheme therefore needs both an identifier that is never reused and a record of the parent-child relationship.

The design requirement can be stated precisely. Let \(S\) denote a fixed candidate state and \(I(S)\) its assigned identifier. The mapping must be one-to-one over the states being managed: if \(S_1\) and \(S_2\) differ in a model-defining way, then \(I(S_1)\) and \(I(S_2)\) must differ. A parent link then records the development relationship without pretending that the new candidate is merely another execution of the old one.

This gives a short justification for creating a new version whenever a model-defining artifact changes. If two distinct states share one identifier, a reviewer cannot determine which state that label denotes. If every distinct state receives a different identifier and the earlier artifact is preserved, the label and its record identify the intended state unambiguously. This does not establish that either candidate is scientifically appropriate; version control preserves what was proposed, not the validity of the proposal.

Recording Branches Without Losing Their Relationships

Competing candidates often arise by branching from a common parent rather than by changing one linear sequence. For example, a hypothetical parent PK-B-v003 may lead to one candidate that adds a weight covariate and another that changes the random-effects structure. Give each branch a unique identifier and name PK-B-v003 as the parent of both. Do not assign both branches the same next revision label, and do not describe one as a revision of the other unless it actually derives from it.

Change Records That Remain Useful

The purpose of a change record is not to reproduce the complete model code in prose. It is to summarize the meaningful delta and point to the immutable artifact that defines the candidate. A useful entry is brief but concrete: “Added a linear weight effect on clearance, centered at 70 kg; parent PK-B-v003; scientific change; model source fingerprint recorded.” An entry such as “updated covariates” is not enough to identify the change.

A practical record can use the following fields:

• Identifier and parent: unique candidate label and the version from which it derives.
• Change class: scientific model change, operational edit, or input/analysis change.
• Change summary: a concise before-and-after description, naming the affected component.
• Rationale: the reason for proposing the change, stated as a motivation rather than a claimed result.
• Artifact reference: a stable location and, where available, a checksum or other integrity fingerprint.

If a revision contains changes from more than one class, keep the classes distinguishable in the record. If the purpose is to isolate one scientific change, make separate revisions for the operational adjustment and the scientific modification. This is especially helpful when an edit’s effect is uncertain: do not declare it operational solely because that was the intent. Record what changed, preserve the artifact, and flag uncertainty about whether it could alter the specification.

Diagnostics, Alternatives, and Limitations

Several warning signs indicate that candidate management is failing: two files have the same supposed version label; a change record says only “updated”; a branch has no stated parent; the recorded checksum does not match the stored artifact; or a model file is edited after its identifier has been assigned. These are not cosmetic defects. They prevent a team from establishing which specification a label denotes.

There are three common approaches. Overwriting a single “current model” file is quick but destroys prior states and makes the meaning of the filename depend on timing. Copying files into folders with informal labels preserves some history but makes parent relationships and change types hard to search. An immutable candidate registry with unique identifiers, parent links, concise change records, and artifact checks is more deliberate, but supports reliable retrieval and review. A version-control system can help preserve file history, but it does not by itself ensure that candidate labels, scientific rationales, input changes, and operational edits are documented in a way the modeling team can interpret.

Version records also have limits. They cannot guarantee that a model is correctly specified, that a change is scientifically justified, or that two candidates are suitable for a later statistical comparison. Nor do they replace records of execution conditions or run outcomes. Their narrower purpose is to keep candidate identities and changes explicit, so later work can refer to the intended model state without guessing.

Common Mistakes

• Reusing an identifier. A label that once named one specification must not be assigned to a different one. Create a new revision instead.
• Treating every code edit as operational. A small edit can change the likelihood, parameterization, data selection, or model assumptions. Classify by effect, not by line count.
• Calling input changes operational. A changed filter or dataset can change the analysis basis. Record it separately from edits that only affect file handling.
• Using “final” or “best” as a version. These are judgments that may change; they do not uniquely identify a fixed candidate state.
• Recording only the change summary. Without a parent link and a reference to the exact artifact, a summary may not establish which state was changed or preserved.