Synthetic data

Provenance manifests

Every call to synthetic.generate writes a provenance manifest alongside its output: a small JSON document that records exactly what produced the data, so a reviewer can either reproduce the run or verify that a shipped sample matches its stated inputs without rerunning anything.

What’s recorded

The manifest ties together four things that, together, fully determine a run’s output: the generator and its version, the seed, the calibration target version, and the environment the generator ran in (captured as a lockfile hash rather than a full dependency list, to keep the manifest small). It also carries a hash chain back to the source data the calibration target was built from, so provenance doesn’t stop at “EU-SILC” as a label — it points at a specific, checksummed release.

{
  "manifest_version": "1.0",
  "run_id": "hp-20260801-7f3a1c",
  "generator": "household_panel",
  "generator_version": "3.1.0",
  "seed": 20260801,
  "n": 10000,
  "calibration_target": "eu-silc-2023-v2",
  "environment_lockfile_sha256": "9e1c2a4b7f0d3e6c1a8b5f2d9c0e3a7b4d1f6c8e2a5b9d0c3f7e1a4b8d2c5f9e",
  "source_data_hash_chain": [
    "eurostat:silc-2023-release:sha256:4a7c1e9b...",
    "eu-silc-2023-v2:derived-moments:sha256:c8f2a3d1..."
  ],
  "generated_at": "2026-08-01T09:14:22Z",
  "output_checksum_sha256": "b1d4f7a2c9e6083b5a1d7f4c2e9b6083a5d1f7c4b2e9068"
}

Reading a manifest

• seed and generator_version together with calibration_target are sufficient to regenerate the sample exactly, given a matching environment.
• environment_lockfile_sha256 is the hash of the resolved dependency lockfile (not the lockfile contents itself) — it lets you confirm two environments are equivalent without shipping the lockfile around.
• source_data_hash_chain lets you walk backward from the calibration target to the specific statistical release it was derived from, without having to trust a plain-text citation.
• output_checksum_sha256 is a checksum of the generated sample itself, so a downstream user can confirm the file they received is the one the manifest describes.

Retrieving a manifest

Manifests are written to disk next to the generated sample by default, and are also retrievable by run ID:

from equilibrium import synthetic

manifest = synthetic.manifest("hp-20260801-7f3a1c")
manifest.seed

The CLI equivalent is equilibrium manifest <run-id> — see the CLI reference.