startthat.work home

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.

Check extracted resultsEvidence: PracticePreparation technique, runs in step 5.2Strongest statement: describe

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

PropertyRequirement typeRequirement
Unit of analysisAlways appliesrequires=dataset
Appraises source credibilityApplies in some casesno

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 materialraw data kept read-only and every processing step scripted
Additional sources needednone
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 techniquePreparation technique, runs in step 5.2
Phase tagverify and prepare
Other phase tagsanalyse; validate; report
Kind of findingrisk; gap
Question answeredwhat
Strongest statement it supportsdescribe
Needs as input
Makes as output
Must exist firstNone
Loop targetreturn 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.

StakesCheckPerson involvedCounts as a different method
exploratoryinput validationnoneno
decision-informinginput validationnoneno
decision-informingprovenance lognoneno
decision-informingspot checkoptionalno
high-stakesinput validationnoneno
high-stakesprovenance lognoneno
high-stakesspot checkoptionalno
high-stakesindependent reviewneededno

Failure modes and limits

Model suitabilitymodel plus code
Typical model failureReports a result without the script that produced it, so it cannot be rerun.
Error sourcesinput data; data transformation
Certainty limitsCertainty drops when any step was done by hand (risk of bias) and when the environment was not recorded (indirectness).

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.