Version-Controlled Analysis¶
Workflow — instantiates Reproducibility Protocol
Uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation.
Version-Controlled Analysis is a working discipline in which every change to the analysis — code, scripts, notebooks, parameter files, documentation — is committed to a version-control system, so the full history of change is preserved and any exact past state can be retrieved on demand. Its defining idea is identity-of-state over time: not a frozen snapshot of one moment and not an automated run, but a walkable timeline in which each result can be tied to the precise revision of everything that produced it. The question it answers is "what was the exact state of the world when this number was generated, and how did we get from there to now?" A commit hash becomes an immutable name for a moment, and every result can carry the name of the moment it came from.
Example¶
A data-journalism team builds an analysis behind an investigation into rising eviction filings. Over three weeks the script changes constantly — a filter is tightened, a county is added, a threshold is nudged. When an editor challenges a chart, the reporter needs to know exactly which version of the code and which vintage of the scraped court data produced that specific figure. Because the whole analysis lives in version control, they check out the commit tagged when the chart was exported: the script at that revision, the parameter file with the threshold as it then stood, and a pinned reference to that day's data snapshot. The figure regenerates, the disputed choice is visible in the diff that introduced it, and the reporter can show precisely when and why the threshold changed. Nothing was reconstructed from memory; the commit graph carried the provenance.[n1] (The investigation is illustrative.)
How it works¶
The mechanism turns "save the file" into "commit a named, immutable state." Three properties do the reproducibility work: inputs are pinned to versions — the data is referenced by an immutable identifier or tracked alongside the code so a checkout resurrects the exact vintage; parameters live in tracked files so every change to a threshold, seed, or setting is a diff with an author and a timestamp, not a silent overwrite; and the commit history is a provenance map — each result links back to the precise revision of code, config, and data that produced it, and forward through the changes that followed. What it does not do is execute the analysis or fix the runtime it executes in; it records which state existed, not how to run it or on what machine.
Tuning parameters¶
- Commit granularity — many small commits or few large ones. Fine commits make history precise and diffs legible; coarse commits are less noisy but blur when a change actually happened.
- Data-in-VCS strategy — reference data by external immutable ID, or track it with a large-file extension. Tracking makes checkouts self-resurrecting; referencing keeps the repository lean but leans on the external store.
- Tag/release discipline — whether result-producing states are explicitly tagged. Tagging makes "the version behind figure 3" instantly retrievable; relying on bare history forces archaeology.
- Branching model — how exploratory work is isolated from the canonical line. Clean branching keeps the main history reproducible; tangled branches make "which state was real?" ambiguous.
- Commit-message rigor — how much rationale each change records. Rich messages turn the log into a why-history; terse ones preserve the what but lose the why.
When it helps, and when it misleads¶
Its strength is total recall of state: any past result can be reconstructed by returning to its commit, every parameter change is attributable and reversible, and the linkage from a result back to its exact revision is automatic rather than remembered. It is what lets a team change an analysis fearlessly, knowing the previous state is never truly lost.
Its failure mode is that version control faithfully tracks only what is committed — and analyses leak. The large dataset that never entered the repository, the parameter typed into a live console, the manual spreadsheet edit outside the tracked files: none of these are in the history, so a checkout resurrects a state that no longer actually reproduces. The tidy commit graph lends false confidence that everything is captured. The classic misuse is versioning the code while the data and environment drift untracked. The guarding discipline is to bring every result-determining input under version control or an immutable reference — a commit that cannot regenerate its own result is a bookmark, not a reproduction.
How it implements the components¶
data_version— inputs are pinned to immutable identifiers or tracked with the code, so any checkout resurrects the exact data vintage behind a result.parameter_log— thresholds, seeds, and settings live in tracked files, making each change an attributed, timestamped, reversible diff.provenance_linkage_map— the commit history links every result to the precise revision of code, config, and data that produced it, walkable both backward and forward.
It does not execute the transformation or fix the machine it runs on — method_record automation belongs to Workflow Script or Pipeline and environment_record to Containerized Environment Snapshot; version control records which state existed, not how to run it or where.
Related¶
- Instantiates: Reproducibility Protocol — the discipline supplies the change-history-and-state-identity strand of the archetype.
- Sibling mechanisms: Workflow Script or Pipeline · Containerized Environment Snapshot · Reproducible Research Package · Replication Package · Rerun Checklist · Protocol Documentation · Lab Notebook Record · Decision Log · Audit Trail
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Version-Controlled Analysis operates as a persistent ledger, log, register, or case record that preserves history and traceability because it uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation.
Independent corroboration: The frozen evidence defines Version-Controlled Analysis as 'Uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation', so its operative form is Record, Log & Register.
Nearest alternative: Protocol, Workflow & Routine — Version-Controlled Analysis includes features of a repeatable ordered procedure or handoff sequence that coordinates action, but its defining operation is a persistent ledger, log, register, or case record that preserves history and traceability.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Universal
Rationale: Both independent reviews identify computer science as the historical home of the operation—Uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation.. The retained alternates document formative adjacent traditions; the reach field, not the origin field, carries later applicability.
Related originating lineages:
- Data Science & Analytics — Data science's modeling, validation, and monitoring tradition contributes a separate formative lineage to the mechanism's version controlled analysis logic.
- Engineering & Design — Engineering design, reliability, and systems-safety practice supplies a parallel or contributing lineage for the mechanism's defining operation: uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation.
Review resolution: Both blind reviewers independently place the defining operation—Uses a version-control system to preserve changes to code, data-processing scripts, notebooks, parameters, and documentation.—in computer science. Their queued differences are secondary: alternate_origin_disagreement, origin_mode_disagreement, encyclopedia_synthesis_disagreement. Reviewer A uniquely contributes ['data_science']; reviewer B uniquely contributes ['engineering_design']. I preserve the full evidence-supported union of 2 alternate domain(s), without a numeric cap. origin_mode=single_lineage reflects the more specific lineage judgment in reviewer B's evidence, while domain_reach=universal separately records present-day portability. The affirmative encyclopedia-synthesis finding is preserved, and confidence=high uses the more conservative reviewer level.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] In a content-addressed version-control system such as Git, each commit is named by a cryptographic hash that immutably identifies the exact state of the tracked files; that hash is what lets a result cite the precise revision that produced it and be resurrected exactly. ↩