Replay an execution receipt

Re-executes a design exactly as recorded in its execution receipt, passing the stored seed, stages, panels, and reps back to execute(). This avoids reconstructing those arguments by hand from the receipt fields.

Usage

replay_design(x, frame, fingerprint = c("error", "warn", "inform", "ignore"))

Arguments

x

A sampling_design carrying an execution receipt, as returned by read_design() for a file written from a tbl_sample. A tbl_sample is also accepted and is replayed from its own metadata, which is useful for verifying reproducibility without a file round trip.

frame

The sampling frame the receipt refers to.

fingerprint

How to respond when frame differs from the fingerprint stored in the design file: "error" (default), "warn", "inform", or "ignore".

Value

The replayed tbl_sample.

Details

Given the same frame and compatible recorded implementations, the replayed sample is identical to the original: the same rows in the same order, the same weights and design columns, and the same .panel and .replicate assignments. Only the execution timestamp differs. Replay restores the execution-time RNG configuration and then restores the caller's RNG state. It warns when recorded R or package versions differ.

Receipts record a single execute() call. A sample produced by several calls (a stage continuation or a multi-phase pipeline) carries a chained flag in its receipt and cannot be replayed; save and replay each phase or stage batch separately.

For a design using a registered custom method, the receipt records a fingerprint of the implementation (the formals and body of the registered sample_fn and joint_fn). Replay refuses when the currently registered function differs from the recorded one, since identical registry metadata does not imply the same selections. The fingerprint normalizes formatting and comments and does not cover the function's enclosing environment: a registered function that reads from its environment can change behavior without changing its fingerprint.

When the design was saved with a frame fingerprint, frame is compared against it before replaying. A differing frame still yields a valid sample, but not the recorded one, so the default is to error. After replaying, the row count is checked against the receipt's n_selected as a final consistency check.

See also

write_design() and read_design() for the receipt round trip, validate_frame() for checking a frame against a design before executing.

Examples

sample <- sampling_design() |>
  stratify_by(region) |>
  draw(n = 100) |>
  execute(bfa_eas, seed = 11, panels = 4)

path <- tempfile(fileext = ".json")
write_design(sample, path, frame = bfa_eas)

replayed <- replay_design(read_design(path), bfa_eas)
identical(replayed$ea_id, sample$ea_id)
#> [1] TRUE
identical(replayed$.panel, sample$.panel)
#> [1] TRUE

unlink(path)