Why Make the Execution Order Explicit?
A pharmacometric analysis is often a sequence of dependent actions: prepare an analysis dataset, validate it, fit a model, then create a summary. If a user must infer which scripts to run, in what order, and from which starting directory, the workflow is vulnerable to omissions and accidental use of stale files. An entry point gives the workflow one explicit, documented starting command and makes its required sequence visible.
An entry point does not need to contain all the analysis code. Its main responsibility is orchestration: check prerequisites, invoke the required steps in the correct order, and stop with useful information if a prerequisite or step fails. The individual scripts carry out the work. The introductory material on portable paths and working directories establishes why a run should also have a clear path context; here the emphasis is on what runs, and when.
The execution order should follow dependencies, not merely a preferred numbering scheme. If a model fit consumes a validated dataset, the dataset must be prepared and validated before fitting begins. A report that consumes model results must run after the fit. In contrast, two checks that use only the same raw input may be independent of each other; either order may be valid if both are required and their effects do not depend on sequence.
Specify Dependencies Before Writing the Entry Point
Represent each workflow step by the files it requires and the artifacts it produces. If step B needs an artifact produced by step A, draw a dependency from A to B. The resulting dependency graph determines which execution orders are valid. A valid order places every prerequisite before the step that consumes it. If a dependency cycle appears—for example, each of two steps requires the other's output—the workflow is not executable as specified and must be redesigned.
The graph can permit more than one valid order. The entry point should choose and document one stable order for the project, rather than leave the choice to each analyst. The following reasoning is the basic justification for this rule: if a step consumes an artifact, that artifact must already exist and represent the current run before consumption. Placing the producer first is therefore necessary. Repeating this requirement for every dependency yields the ordering constraints for the full workflow.
Identify the input files and software or other conditions that must be available before any work can start.
For each step, state what it reads and what it must produce for later steps.
Place every producer before the step that requires its artifact, and record the chosen order in the entry point or its accompanying instructions.
Check inputs before starting, and check important outputs after their producer runs but before a dependent step uses them.
Do not run downstream steps when a prerequisite check or required workflow step fails.
These checks do not replace validation of dataset contents. File existence only establishes that a path resolves to a file; it does not establish that the file has the right schema, units, records, or values. Those substantive checks belong in the appropriate data-preparation and validation steps. The entry point can still ensure that the validation step runs before model fitting.
Worked Example: Orchestrating a Dataset-to-Model Workflow
Suppose a hypothetical project has two required source files: data/raw/concentration.csv and data/raw/dosing.csv. The preparation script reads both and writes data/derived/analysis.csv. A validation script reads that file and writes data/derived/analysis_validated.csv. The model script requires the validated file. Assume the project is run from its documented project root and the R scripts use the listed paths.
The dependency order is: source files, then preparation, then validation, then model fitting. One possible R entry point, saved as run_analysis.R in the project root, is shown below. Each line is part of the same script.
required = c("data/raw/concentration.csv", "data/raw/dosing.csv")
missing = required[!file.exists(required)]
if (length(missing) > 0) {
stop(paste("Required input file(s) missing:",
paste(missing, collapse = ", ")), call. = FALSE)
}
source("scripts/01_prepare_data.R")
if (!file.exists("data/derived/analysis.csv")) {
stop("Preparation did not create data/derived/analysis.csv", call. = FALSE)
}
source("scripts/02_validate_data.R")
if (!file.exists("data/derived/analysis_validated.csv")) {
stop("Validation did not create data/derived/analysis_validated.csv", call. = FALSE)
}
source("scripts/03_fit_model.R")
The first two lines create a list of prerequisites and select any that are not available. If both files exist, missing has length zero, so the conditional does not stop execution. The preparation script then runs before validation. The explicit file check tests whether preparation created its expected artifact before validation is asked to use it. The same logic ensures the validated artifact exists before model fitting begins. Run the entry point with the documented command Rscript run_analysis.R.
This example assumes each script returns control normally when successful and signals an error when its own operation fails. In R, an uncaught error during source() interrupts the entry point, so later lines are not reached. A script that catches and suppresses its own failure can defeat this protection; such a script must report failure in a way the caller can detect. The assumption should be part of the workflow contract, not left implicit.
Fail Clearly and at the Right Time
A useful failure message answers three practical questions: what was required, what was unavailable or unsuccessful, and what should the user check next? “Error” is not enough. “Required input file missing: data/raw/dosing.csv; check that the source file is present under the project root” gives a more direct route to resolution. Messages should identify paths or step names precisely and should not expose sensitive data unnecessarily.
Check all simple prerequisites that can be checked before starting expensive or consequential work. If one of several required source files is absent, report the missing file or files before running preparation. Then check critical intermediate artifacts immediately after their producing steps. This separates an initial-input problem from a failure during preparation or validation. It also prevents an absent output from being misreported later as a model-fitting problem.
Do not treat an old intermediate file as proof that the current run succeeded. If a preparation script fails but an artifact from a previous run remains, a mere file-existence check might pass. One remedy is for a step to write its output only after it has completed successfully, with failures propagated to the entry point. Another is to use run-specific output locations, but the general organization of run folders and output naming requires a separate design decision. At minimum, define what counts as a successful step and avoid continuing on artifacts whose freshness is uncertain.
The entry point also needs a clear contract about its environment: the documented invocation, expected project root, required inputs, and sequence of actions. It should not depend on a user having first run several undocumented commands in an interactive session. Requiring hidden objects or options left over in a console makes a run difficult to reproduce because a clean process may behave differently. Keep the required conditions explicit and make the entry point responsible for checking those that can be checked reliably.
Worked Example: Diagnosing a Missing Required Input
Consider a hypothetical run in which data/raw/concentration.csv exists but data/raw/dosing.csv does not. With the prerequisite check in the entry point, the vector missing contains the single path data/raw/dosing.csv, so length(missing) equals 1. Since 1 is greater than 0, the script calls stop() before sourcing the preparation script.
The resulting message is equivalent to: Required input file(s) missing: data/raw/dosing.csv. No preparation, validation, or model-fitting step has run. The appropriate conclusion is that this run is incomplete because a required source file is unavailable—not that the data passed validation, or that a model failed to converge. The user should restore or correctly locate the specified file, then rerun the entry point.
If the entry point instead began by fitting the model and only encountered the absent file later, it would have failed at a less informative point. If it skipped the missing file and continued, it could produce an analysis based on incomplete inputs. Checking the full required-file list first makes the failure earlier and more diagnostic.
Compare Execution Approaches and Diagnose Failures
An alternative is to instruct analysts to run each script manually in order. This can work for a small, genuinely interactive task, but it makes correct order depend on memory and offers no single place to check prerequisites. Another alternative is to put the entire workflow in one large script. That can make execution sequential, but it can also make the sequence hard to inspect and individual steps harder to run or review. An entry point that invokes distinct workflow scripts provides a visible sequence without requiring the orchestration file to contain all the analysis logic.
| Approach | Strength | Main risk |
|---|---|---|
| Run scripts manually | Simple for an occasional interactive task | A step can be omitted, repeated, or run out of order |
| One large script | One command and an obvious linear execution path | Orchestration and analysis logic can become difficult to inspect separately |
| Entry point calling workflow steps | One documented command, visible sequence, and central prerequisite checks | Depends on scripts reporting failure correctly and on a clear path context |
When a run behaves unexpectedly, diagnose the workflow at its boundaries. Confirm the documented command and project root, inspect the initial prerequisite checks, determine the last step that completed, and verify that the expected artifact from that step was produced during the current run. Then inspect the error from the first failed step rather than interpreting symptoms from a later step. A downstream error may only be a consequence of an earlier missing or malformed artifact.
There are limits to what an entry point can guarantee. A file may exist but be unreadable, corrupted, or inconsistent with the expected data specification. A script may complete while generating scientifically inappropriate results. A dependency order can be reproducible but still be wrong if it encodes the wrong scientific process. Therefore, the entry point supports reproducibility and clear control flow; it does not certify scientific validity. Data validation, model diagnostics, and review of the analysis remain necessary.
Worked Example: Choosing a Valid Order From Dependencies
Suppose a hypothetical workflow has four steps. Step A prepares a dataset from raw records. Step B validates A's dataset. Step C fits a model using B's validated dataset. Step D creates a model summary using C's fit results. The dependencies are therefore A before B, B before C, and C before D.
One valid sequence is A, B, C, D. Check each dependency: A occurs before B; B occurs before C; and C occurs before D. A sequence such as A, C, B, D is invalid because C occurs before B, even though A occurs first. At the point C runs, the validated dataset it requires has not yet been produced. The fact that B appears somewhere in the same workflow does not repair the ordering error.
If there were an additional step E that checked only the raw records and neither consumed nor produced an artifact used by A through D, E could be placed before A, between A and B, or after D without violating those listed dependencies. The project may still choose a single position for E to make runs predictable. If E actually produces an input required by A, however, the dependency changes and E must precede A. Thus, the correct order follows declared inputs and outputs, not the script filenames alone.
Common Mistakes
- Starting with the model script. A model script is not a reliable entry point if required data-preparation and validation steps must happen first. Run the orchestration script that states the complete sequence.
- Assuming a file exists because its directory exists. Check the exact required file path. A directory is not a usable input dataset.
- Checking only at the end. If a prerequisite is missing, detect it before expensive work. If an intermediate artifact is missing, detect it before its consumer runs.
- Continuing after a failed prerequisite. Skipping a failed step can yield outputs based on incomplete or stale artifacts. Stop and identify the first failure instead.
- Treating file existence as data validation. A present file can still have the wrong structure or contents. Existence checks and substantive validation answer different questions.
- Documenting an order that the entry point does not implement. Keep instructions and actual orchestration consistent, or users may reproduce a different workflow than the one intended.
Check Your Understanding
Answer each question, then compare with the solutions below.
- A preparation step creates a dataset, a validation step reads that dataset and creates a validated version, and a model step reads the validated version. What order must the entry point use?
- Why is checking that an input file exists not sufficient to establish that it is ready for model fitting?
- An entry point reports that a required dosing file is missing before any workflow step runs. What conclusion is justified, and what conclusion is not justified?
- Two steps both read the same raw file, and neither consumes the other's output. Does dependency information alone require one to run first?
- A preparation script fails, but a file with the expected output name remains from an earlier run. Why can a simple existence check be misleading?
Solutions. 1. Run preparation, then validation, then model fitting: each producer must run before its dependent consumer. 2. Existence confirms only that a file is present at a path; it does not establish readability, schema, units, completeness, or valid contents, so appropriate validation is still required. 3. The run cannot proceed as specified because a required input is unavailable. It is not justified to conclude that the data passed validation or that a model fit succeeded. 4. No. If neither step depends on the other's output and their effects do not otherwise require ordering, either sequence satisfies those dependencies, although the entry point should document a chosen order. 5. The file may be stale and may not reflect the current run. A workflow needs a success contract that prevents downstream use of an output when its producer failed.