Export a simulation run as a self-describing bundle

Writes a simulated cohort, the fidelity metrics that judge it, the deck it was drawn over, a README and a manifest.json into one archive that can be handed to someone who was not in the room. The archive is the return value, so the whole function is a one-liner inside a Shiny downloadHandler().

Usage

sdt_export_simulation(
  x,
  path,
  format = c("csv", "parquet", "rds"),
  metrics = NULL,
  overwrite = FALSE,
  pseudonymise = TRUE,
  crosswalk = NULL,
  allow_git = FALSE,
  zip = TRUE,
  verbose = TRUE
)

Arguments

x: A sdt_simulated_groups table from sdt_simulate_groups(), or any data frame with sim_group and card columns. Model provenance is read from attr(x, "model") or attr(x, "meta") when present.
path: Destination. With zip = TRUE the archive is written at exactly this path — pass a .zip name in a script, or the file argument of a downloadHandler() unchanged. With zip = FALSE it is the directory to fill.
format: Storage format for the tables: "csv" (widest compatibility), "parquet" (via nanoparquet) or "rds" (lossless R). The README and manifest are always plain text.
metrics: A fidelity table from sdt_fidelity(). Defaults to attr(x, "fidelity") when that is present. A bundle without metrics is written, and says in as many words that it makes no fidelity claim.
overwrite: Overwrite an existing destination?
pseudonymise: Replace course identifiers with stable codes? Defaults to TRUE; see the section above before turning it off.
crosswalk: Optional path, outside the bundle, for the pseudonym crosswalk as CSV. NULL discards the mapping.
allow_git: Permit a destination inside a git working tree?
zip: Write a single archive (TRUE) or a directory (FALSE)?
verbose: If TRUE, report what was written via cli.

Value

Invisibly, the written paths: the archive when zip = TRUE, the member files otherwise. The archive path is always the first element, and carries the member names in attr(., "members").

What the bundle contains

simulated-groups.* — one row per simulated group and card.
fidelity-metrics.* — the output of sdt_fidelity(), when supplied.
deck-cards.* — the cards the simulation ranged over.
README.md — generated at write time; carries the caveats.
manifest.json — versions, seed, frame, model terms, random-effect SDs, skipped outcomes, the privacy scheme, and a SHA-256 of every other file.

Refusals

The writer aborts rather than doing something quietly regrettable:

an existing destination is never overwritten unless overwrite = TRUE;
a destination inside a git working tree is refused unless allow_git = TRUE, because synthetic rows that get committed are read as real data by the next person;
with pseudonymise = TRUE the written bytes are searched for the original identifiers before the file is closed, and a survivor is an error.

Pseudonymisation

Session identifiers and scenario names in this domain embed hospital, venue and city names and the exact course date. They are therefore mapped to S01…Snn, groups to G001…Gnnn and scenarios to SC01…SCnn by default. The crosswalk is written only if crosswalk names a path, and that path must lie outside the bundle; otherwise the mapping is discarded when the function returns and the bundle cannot be re-identified from itself.

Examples

sim <- tibble::tibble(
  sim_group = rep(c("sim_01", "sim_02"), each = 2L),
  card = rep(c("01", "02"), 2L),
  red = c(TRUE, FALSE, TRUE, TRUE)
)
out <- sdt_export_simulation(
  sim,
  tempfile("demo-bundle-", fileext = ".zip"),
  verbose = FALSE
)
utils::unzip(out, list = TRUE)$Name
#> [1] "demo-bundle-1ab3218fc4da/"                    
#> [2] "demo-bundle-1ab3218fc4da/simulated-groups.csv"
#> [3] "demo-bundle-1ab3218fc4da/manifest.json"       
#> [4] "demo-bundle-1ab3218fc4da/README.md"           
#> [5] "demo-bundle-1ab3218fc4da/deck-cards.csv"      

# In Shiny, the handler's `file` is the archive path:
# downloadHandler(
#   filename = function() "simulation-bundle.zip",
#   content = function(file) {
#     sdt_export_simulation(sim, file, metrics = fid, verbose = FALSE)
#   }
# )