Why Artifact Boundaries Matter
A pharmacometric project may contain analysis scripts, model-control files, clinical and assay data, derived datasets, diagnostic plots, and temporary files created during a run. If these materials are mixed together without clear boundaries, a reviewer may not know which files are authoritative, which can be regenerated, or which must remain unchanged. The resulting confusion can undermine traceability even when the model code itself is sound.
The earlier material on A Portable Pharmacometric Project Layout established that a project benefits from an intentional structure. Here the focus is the rule behind that structure: classify each artifact by its role and governance, then place it with other artifacts that share those properties. A folder name alone does not make a file an input, source, or output; its role in the workflow does.
These categories describe different properties, so one distinction should not be mistaken for another. A governed source may be copied into a controlled project as a workflow input, but the copy does not become the authoritative source. A configuration file may be an input to execution in the broad sense, yet it remains a maintained instruction rather than an observation. A derived dataset is generated even if it becomes an input to a later modeling step.
Classify by Role, Ownership, and Life Cycle
For each artifact, ask three questions. First, what role does it play? Does it provide observations, specify how the workflow should operate, or result from execution? Second, who has authority to change it? Is it governed by a data owner, maintained by the analysis team, or disposable because it can be regenerated? Third, what is its life cycle? Must it be preserved as received, reviewed and edited, retained as a result, or removed after a run?
The answers determine a practical placement. Maintained scripts and project-controlled configuration belong together in the maintained part of the project, separate from supplied records. Governed source material belongs in a clearly identified source area or in an authorized external location referenced by the workflow. Inputs prepared or selected for a run belong in an input area. Temporary intermediates belong in a clearly identified working area. Retained results belong in an output area, apart from both the code that generates them and the inputs from which they were produced.
| Artifact class | Examples | Placement rule | Default handling |
|---|---|---|---|
| Maintained code and configuration | Data-preparation script, model-control file, project settings | Keep with other reviewed project instructions | Edit deliberately; do not treat as observed data |
| Governed source | Released clinical extract, assay transfer, source reconciliation record | Keep in a distinct source area or approved governed location | Preserve as received; follow access and change controls |
| Workflow input | Approved analysis dataset selected for a run | Place where the workflow expects supplied materials | Do not silently overwrite; record its origin |
| Temporary intermediate | Join table, transformed working dataset, software scratch file | Keep separate from preserved inputs and retained results | Regenerate or discard when appropriate |
| Retained generated output | Final analysis dataset, parameter table, diagnostic report | Keep apart from inputs and maintained instructions | Retain when required; label its relationship to the run |
“Input” and “output” are relative to a workflow step. For example, a dataset generated by a preparation script can be an input to a model-fitting step. This does not change its history: it remains a generated dataset from the first step and a supplied input to the second. Clear boundaries preserve that lineage instead of flattening every file into one vague “data” category.
A Simple Lineage Rule
A useful way to justify the boundaries is to represent the workflow as a chain of dependencies. Maintained instructions and selected inputs determine what a process does; its generated artifacts are consequences of that process. If a generated artifact is edited directly and then treated as authoritative, the chain no longer explains how its contents arose. Likewise, if a governed source is overwritten during preparation, the project loses a reliable reference point for checking transformations.
This is a conceptual lineage, not a claim that every project has exactly one source or a single linear process. Workflows can branch, combine sources, or use several stages. The placement rule still follows: preserve governed records and maintained instructions as distinct classes, and identify generated materials according to whether they are temporary or retained.
Decide whether it records observations, instructs a process, is supplied to a process, or is created by execution.
Determine whether a data owner governs it, the project team maintains it, or it is a reproducible by-product.
Keep preserved sources, maintained instructions, supplied inputs, temporary intermediates, and retained outputs distinguishable.
Confirm that someone can tell what generated a result and which source and instructions were involved.
Worked Example: Classifying a Clinical Data Transfer
Suppose a hypothetical analysis receives a released clinical extract from a data-management group. The analyst uses a maintained script to derive study day and an analysis-population flag, then creates a dataset for model fitting. Classify the files and decide where they belong.
The released extract is a governed source: it is supplied by a responsible group, and the analysis team should not silently correct or replace its records. Keep it in the designated source area or access it from an authorized governed location. The derivation script is a maintained artifact, because the project team reviews and changes it. It belongs with project instructions, not beside the released records as if it were part of the transfer.
The derived dataset is a generated artifact. If it is an intermediate used only to create the model-fitting dataset, keep it in the working area and make it reproducible from the source and script. If it is the approved dataset supplied to model fitting or retained for review, treat it as a workflow input to that step or a retained output of preparation, while recording its generated origin. It should not be mislabeled as the original source.
The classification follows role and history rather than file format: all three materials could be tabular or text files, but they have different authority, change rules, and places in the lineage.
Worked Decisions in a Modeling Workflow
Worked Example: Separating a Model Run’s Inputs and Results
Consider a hypothetical project with an approved concentration-time dataset, a model-control file, a run-specific settings file maintained by the team, a software-generated table of individual predictions, and a diagnostic report saved for review. Where does each item belong?
The approved concentration-time dataset is a workflow input for model fitting. Its upstream history may make it a generated output of data preparation, but it should remain distinct from the modeling instructions. The model-control file and settings file are maintained artifacts: they define model structure or execution choices and should be reviewed as project-controlled instructions.
The prediction table is generated. If it is an automatically recreated working file used only by downstream diagnostics, it is an intermediate. The diagnostic report is also generated, but because it is retained for review, it belongs with retained outputs rather than temporary working files. In both cases, do not manually modify the generated file and then imply that it is the direct result of the stated model run.
This distinction makes a practical difference during review. A reviewer can inspect the input dataset and maintained instructions separately from the prediction table and report, and can ask whether the results correspond to the intended run without mistaking results for source material.
Worked Example: Deciding Whether a File Is Temporary
A hypothetical preparation script creates a joined laboratory-and-clinical table, then uses it to make a validated analysis dataset. The joined table is not distributed for review, but it helps diagnose mismatched subject identifiers during preparation. Should it be retained as an output?
Its role is a generated intermediate: it is created to support a later transformation, not designated as the final dataset or a deliverable. Its appropriate home is the temporary working area, separated from preserved source data and retained outputs. If a review or quality-control requirement makes the joined table a required record, that requirement changes its retention status; it should then be handled as a retained artifact with its origin documented.
The decision is not based on whether the table is useful. Temporary files can be valuable during debugging. The relevant question is whether the workflow or governance process requires that artifact to be preserved as a result. Where the answer is no, make clear that it is reproducible working material and avoid allowing it to appear to be the authoritative analysis dataset.
Diagnostics, Alternatives, and Failure Modes
A project’s boundaries are not working well if a team member cannot answer basic questions without guessing: Which file is the governed source? Which dataset was supplied to the model? Which script produced this table? Is this report final or a leftover from an earlier run? Those questions are practical diagnostics of the structure, not merely documentation concerns.
One alternative is to put every data-like file in one shared directory. That can seem simple, but it places source records, intermediate tables, and final analysis datasets side by side. The organization then relies on memory or informal labels to distinguish their authority and life cycle. Another alternative is to keep only final outputs and discard all intermediate files. This can reduce clutter, but it may be unsuitable where intermediate artifacts are required for review or troubleshooting. Neither approach is universally correct; the governing requirements and workflow purpose decide what must be preserved.
- Source overwritten during preparation: a transformation edits a released transfer in place. Keep the governed record unchanged and create transformed data separately.
- Generated file treated as maintained truth: someone hand-edits a result and later assumes the workflow will reproduce that edit. Correct the maintained instructions or create an explicitly governed manual adjustment process instead.
- Temporary and retained files mixed together: a stale intermediate looks like a current deliverable. Separate working material from retained outputs and identify the status of results.
- Inputs detached from their origin: a model-fitting dataset is present but its upstream source or preparation step is unclear. Preserve enough lineage to identify how it was produced.
- Configuration confused with observations: a setting such as a study cutoff date is stored among clinical records. Keep instructions and observed data conceptually and physically distinct.
These boundaries have limits. They do not, by themselves, prove that a dataset is correct, that a source was authorized for use, or that a model run can be reproduced. Nor does classifying an artifact as an output decide how long it must be retained; that depends on project, institutional, and regulatory requirements. The structure makes responsibilities and lineage clearer, but it does not replace data governance, validation, or review.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A released assay transfer is copied into a project and used to derive a concentration dataset. Which file is the governed source, and what is the derived dataset?
- A model-control file and a final diagnostic report are both text files. Why should they not be placed in the same artifact category?
- A generated table is used as the input to a later workflow step. Does that make it an original source? Explain.
- A temporary join is required by a project’s formal review process. Should it remain temporary? What changes in its classification?
- What is one warning sign that source files and generated files have not been adequately separated?
Solutions. (1) The released transfer remains the governed source. The concentration dataset is generated by the derivation workflow; if selected for a later step, it is also that step’s input. (2) The model-control file is a maintained instruction, while the report is a generated result retained for review. File format does not determine role. (3) No. Its history remains generated; it is an input only relative to the later step. (4) It should be retained as a review-required generated artifact, rather than treated as disposable temporary material. (5) For example, a team member cannot tell which file is authoritative or whether a table is a current result or a leftover intermediate.