Output contract

BNR info-hub Technical Manual

1 Output contract

1.1 Purpose

This page defines the contract between the Stata compute layer and the Quarto publication layer.

The contract exists so that Stata users can generate outputs, reviewers can inspect them, and Quarto pages can publish them without hiding analytical logic inside the website.

1.2 Core model

Stata -> outputs/public/ -> site/downloads/files/ -> Quarto site

1.3 Why a contract is needed

The project needs a stable handover point between computation and publication.

Stata should not need to know how the website is styled. Quarto should not need to know how the analysis was computed.

The output bundle is the handover point.

1.4 Canonical output bundle

For a static briefing, Stata writes to:

outputs/public/briefings/{briefing_id}/

Example:

outputs/public/briefings/cvd_cases_2023_v1/
├── tables/
├── figures/
├── data/
├── meta.yml
└── build.yml

1.5 File roles

File or folder Purpose
tables/ public CSV tables for users
figures/ public PNG figures for display or download
data/ public figure-ready or chart-ready CSV data
meta.yml curated public metadata for the release bundle
build.yml build record describing how and when the bundle was created

1.6 Site-accessible copy

Quarto can only publish files that are available under the site/ source tree or generated during render.

After review, copy Stata-generated public files from:

outputs/public/briefings/{briefing_id}/

to:

site/downloads/files/briefings/{briefing_id}/

Example:

outputs/public/briefings/cvd_cases_2023_v1/
→
site/downloads/files/briefings/cvd_cases_2023_v1/

1.7 Why not write Stata directly into site/?

Writing directly into the site folder would blur the review boundary.

The safer workflow is:

run Stata -> inspect canonical bundle -> copy approved artefacts -> render Quarto

This prevents draft outputs from appearing in the website by accident.

1.8 PDF exception

Quarto-generated PDF briefings are different from Stata-generated files.

A PDF briefing is generated by Quarto from a PDF-focused QMD file. It does not need to be copied back into site/downloads/files/ unless the team chooses to include a frozen PDF in a ZIP release bundle.

1.9 Required checks

Check that:

  • the briefing ID is correct
  • all expected files exist
  • no confidential data files are present
  • filenames are short but understandable
  • meta.yml and build.yml are present
  • figures open correctly
  • CSV files contain only approved public data

1.10 Minimum static briefing bundle

For the case-count pilot, the expected bundle is:

outputs/public/briefings/cvd_cases_2023_v1/
├── tables/
│   ├── cases_2023_sex_event.csv
│   └── age70_2023_sex_event.csv
├── figures/
│   ├── cases_2023_cum_week.png
│   └── cases_2023_age70.png
├── data/
│   ├── cases_2023_cum_week.csv
│   └── cases_2023_age70.csv
├── meta.yml
└── build.yml

1.11 Working rule

If an output is wrong, update the Stata script and regenerate it. Do not manually edit generated files in the output bundle.

Back to top