shg_save_config: Save a portable reproducibility config as YAML

In SmokingHistoryGenerator: R Package for the Smoking History Generator

Save a portable reproducibility config as YAML

Description

Writes a YAML file containing smok_params_source, mort_params_source, mort_params_type, engine settings (RNG, seeds, effective segment count), fixed-run parameters (repeat, race, sex, cohort_year), and immediate_cessation_year. Omits derived paths so the bundle stays portable; those paths are restored by shg_load_params.

Usage

shg_save_config(shg, path, quiet = FALSE, results = NULL)

Arguments

shg	An SHGInterface instance.
path	Destination file path (usually .yml or .yaml).
quiet	If TRUE, suppress the explanatory message printed on save.
results	Optional simulation data.frame; when supplied, the YAML includes a results block (content_md5, summary) and a single repro_digest (MD5 of engine settings plus R session string) for verification (see run bundles from shg_run with attach_run_info = TRUE). Summary uses never_smokers / ever_smokers with count and fraction (YAML reserves bare n); ever_smokers$cpd_mode is the most common rounded CPD among ever smokers. Mean/sd blocks use n_obs (finite values excluding -999). Initiation and cessation means are among ever smokers only; age_at_death$ever_smokers holds death-age stats (not the same list as top-level ever_smokers). age_at_death subgroup n_obs can be smaller if age is missing or sentinel for some individuals. The simulator encodes never smokers with smoking_initiation_age == -999, not NA; NA initiation is excluded from never_smokers, top-level ever_smokers, and those ever-only means.

Details

Prefer the method form shg$save_config(path) (same implementation). The functional form shg_save_config(shg, path) is a convenience wrapper.

Saving reads shg$getReproConfig(debug = FALSE) after your workflow. Portable save is allowed only when the last completed simulation on this instance was runSimFromFixedValues — a subsequent runSimFromDataFrame (population run) clears that until you run runSimFromFixedValues again. Use shg$last_completed_sim_was_fixed_cohort() to test programmatically.

The run scalars (repeat, race, sex, cohort_year) come from that fixed cohort run. Engine fields (number_of_segments, rng_strategy, seeds) reflect effective values from it when you used defaults or auto settings for segments. Thread count is intentionally omitted from the portable repro file (outcomes must not depend on it). Optional results adds content hashes and compact numeric summaries for verification. If results is omitted, the YAML has no results block and no repro_digest (only engine and cohort fields for portability).

If the last run was not a fixed cohort simulation, or fixed cohort metadata are missing, saving fails with an error.

Value

path, invisibly.

See Also

shg_load_config, shg_run

Examples

shg <- new(SHGInterface)
shg$input_data_folder <- system.file("extdata", "2018", package = "SmokingHistoryGenerator")
shg$smok_params_source <- "example-smoking"
shg$mort_params_source <- "example-mortality"
shg$mort_params_type <- "acm"
sim <- shg$runSimFromFixedValues(500, 0, 0, 1950)
tf <- tempfile(fileext = ".yml")
shg_save_config(shg, tf, results = sim)

SmokingHistoryGenerator documentation built on June 13, 2026, 1:08 a.m.