CK-29 Scripted reproducible workflow (reproducible analysis; version control; literate programming)
Record data, code and environment so that another person or a later run can regenerate every figure, and produce a project record that can be rerun from the raw data.
What it does
Records data, code and environment so that another person or a later run can regenerate every figure. Artefact: a project directory with raw data, scripts, a dependency list and test data. Read whether the outputs can be regenerated from the raw data by running the scripts.
When to use it
Use when results must be reproducible by someone else or by a later run from the raw data.
When it does not fit
A fresh run from raw data reproduces the results. Misfit: manual spreadsheet edits or untracked cleaning steps. Reproducing a number does not show it is correct.
Result format
The result describes a project directory holding the raw data, the scripts, a dependency list and test data. It states whether the outputs were regenerated from the raw data by running the scripts and lists any step that could not be regenerated.
Requirements on the material
| Property | Requirement type | Requirement |
|---|---|---|
| Unit of analysis | Always applies | requires=dataset |
| Appraises source credibility | Applies in some cases | no |
Not restricted on: Structure, Content type, Variable types, Time structure, How the sample was chosen, Level of detail available, Number of sources, Whether sources can be joined, Amount of material, Known data problems, Producer interest, Source dependence, Origin, Document genre, Language, Personal information, Security classification, Licence.
| Minimum material | raw data kept read-only and every processing step scripted |
|---|---|
| Additional sources needed | none |
| Not for (rules) | none |
| Not for (text) | Wrong choice when cleaning was done by manual spreadsheet edits that cannot be scripted. Reproducing a number does not show that it is correct. |
Choosing and ordering
| Kind of technique | Preparation technique, runs in step 5.2 |
|---|---|
| Phase tag | verify and prepare |
| Other phase tags | analyse; validate; report |
| Kind of finding | risk; gap |
| Question answered | what |
| Strongest statement it supports | describe |
| Needs as input |
|
| Makes as output |
|
| Must exist first | None |
| Loop target | return to verify and prepare |
Library checks by stakes
Each stakes level includes the checks of the level below it. Checks that need a person apply at high stakes only, so the process leaves them out at lower stakes (decision 38). Repeatability: deterministic.
| Stakes | Check | Person involved | Counts as a different method |
|---|---|---|---|
| exploratory | input validation | none | no |
| decision-informing | input validation | none | no |
| decision-informing | provenance log | none | no |
| decision-informing | spot check | optional | no |
| high-stakes | input validation | none | no |
| high-stakes | provenance log | none | no |
| high-stakes | spot check | optional | no |
| high-stakes | independent review | needed | no |
Failure modes and limits
| Model suitability | model plus code |
|---|---|
| Typical model failure | Reports a result without the script that produced it, so it cannot be rerun. |
| Error sources | input data; data transformation |
| Certainty limits | Certainty drops when any step was done by hand (risk of bias) and when the environment was not recorded (indirectness). |
Related techniques
- pairs with CK-28 Provenance tracking and audit logging (W3C (World Wide Web Consortium) PROV; lineage; record keeping): provenance records which source and decision produced each output
Evidence and tag basis
Practice. Practitioner recommendations published by researchers: keep raw data read-only, use tidy data, script every processing step, make dependencies explicit and use version control. (Good enough practices in scientific computing)
Tag basis: input profile inference; selection inference; sequencing inference; robustness inference. All tag values are inference unless a source is named.