Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Reproducible Reporting

A Reproducible Research Workflow in Stata

Build a reproducible Stata project: folder structure, master do-file, version and seeds, data provenance, checksums, ssc packages, Git and dyndoc.

A result is reproducible when someone else, or you in two years, can start from the raw data and the code and get the same numbers. That sounds obvious and is surprisingly rare. Files get edited by hand, packages change, random steps use different seeds, and nobody remembers which dataset produced Table 2. A few habits fix almost all of it.

Stata cannot run here, so Stata commands are read-only and we do not show Stata output. The runnable blocks are Python stand-ins: a file checksum manifest and a pipeline-order checker, which illustrate ideas that apply to any language.

The five rules

  1. Raw data are read-only. Never edit them; every change is made by code that writes a new file.
  2. One command regenerates everything. A master do-file runs the whole pipeline in order.
  3. No hand-typed numbers. Tables and figures are written by code (tables, exports).
  4. Randomness is controlled. Set the seed and the version.
  5. The environment is recorded. Stata version, user-written packages, operating system.

Project layout

Text
project/
  README.md             what this is, how to run it, data sources and licences
  master.do             runs everything
  data/raw/             original files, never edited
  data/clean/           generated
  code/                 01_clean.do, 02_merge.do, 03_models.do, 04_tables.do
  output/tables/  output/figures/
  logs/
  ado/                  project-local copies of user-written commands

The README records where every raw file came from (URL, date downloaded, version, licence), the variable dictionary or a link to it, and which script produces which output.

The master do-file

STATA
* master.do -- run everything from the raw data
version 18
clear all
set more off
set seed 20250101
global root "`c(pwd)'"          // run Stata from the project folder
adopath ++ "$root/ado"         // use project-local commands first

capture log close
log using "$root/logs/master.log", replace text

do "$root/code/01_clean.do"
do "$root/code/02_merge.do"
do "$root/code/03_models.do"
do "$root/code/04_tables.do"

display "Finished: `c(current_date)' `c(current_time)' on Stata `c(stata_version)'"
log close

c() holds system values, such as c(stata_version), c(os), c(current_date) and c(pwd). Printing them into the log records where and when the run happened. In batch mode, Stata exits with a non-zero code if a script fails, which continuous-integration systems detect. See the do-file basics for each header item.

Dependencies: user-written packages

Packages installed with ssc install change over time. For a published project:

STATA
ssc install estout, replace
which esttab                       // prints the file and its date
ado describe                       // lists installed packages

Record the versions (which shows a *! version line) in the README, and save the ado-files in the project's ado/ folder. Stata 18 also offers net install ..., from(url) for a pinned copy from GitHub, and the version statement keeps core commands stable across releases. The newest Stata may still produce slightly different results for the same code with random numbers or bootstrap, so record the exact release.

Data provenance and integrity

Use datasignature to detect any change in a dataset, codebook, compact to document it, and label data and notes to leave a trail inside the file:

STATA
use "data/clean/survey.dta", clear
datasignature set
notes: Created by code/01_clean.do on `c(current_date)'
save "data/clean/survey.dta", replace

Later, datasignature confirm stops with an error if the data changed. assert statements about ranges, uniqueness and merge results (assert _merge == 3) are executable documentation of what you believe about the data. Outside Stata, a checksum file (SHA-256) for each raw file does the same job.

Python Checksum manifest for raw files (Python stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Version control with Git

Keep code, README and small files in a Git repository; do not commit confidential or very large data. Commit often with clear messages, tag the version used for a paper (git tag paper-v1), and add a .gitignore for *.log, data/clean/ and temporary files. A repository is also the best backup of your history: you can answer "what changed between the draft and the final table?" with git diff.

Literate programming

Stata can mix text and results in one document:

STATA
dyndoc "report.txt", saving("report.html") replace

dyndoc processes Markdown with embedded <<dd_do>> Stata blocks and <<dd_display: ...>> inline results, producing HTML. docx2pdf, putdocx and putpdf are alternatives. The user-written markstat and texdoc do the same for Markdown and LaTeX. Jupyter users can run Stata through nbstata or the stata_kernel. The principle is the same everywhere: text and code live in one place, and numbers are computed.

Pipeline-order checker (stand-in)

A pipeline is a chain of scripts that each read and write files. If a script is run before its inputs exist, results silently come from stale files. The block below models the dependency list and finds a valid order.

Python Dependency order of scripts (Python stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Your master do-file should call the scripts in exactly such an order, and the numbered file names make the order visible.

Test your reproducibility

The best test: copy the project to a new folder (or ask a colleague), delete data/clean and output, run master.do, and compare the output with diff or datasignature. If anything breaks, you found a hidden dependency. Do it before you submit a paper, not after a reviewer asks.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should happen to raw data files?

    Read-only raw data plus code that derives everything else is the core of reproducibility.
  2. 2. Why set both version and a seed in the master file?

    version fixes how commands are interpreted; set seed fixes the random-number stream.
  3. 3. What does datasignature confirm do?

    It compares a stored signature with the current data and errors if they differ.
  4. 4. Which is the best final reproducibility test?

    Only a clean end-to-end run reveals hidden dependencies and stale files.

Summary

  • Keep raw data read-only, run everything from one master do-file, and write all outputs by code.
  • Record version, seed, package versions, system info and data provenance; use datasignature and assert.
  • Use Git, a README and, where useful, dyndoc for literate reports.
  • Python blocks are stand-ins for checksums and dependency order.

Next: Project: wage regression