save_results() writes <results>/results.qs2, the one results object of
the project version. It stops before it writes when check_results()
finds a failure.
Arguments
- ...
The results, each as a named argument, for example
estimates = eorp_interaction = 0.04. Give at least one. Each name MUST be syntactic and MUST be there once. A result namedmanifestis an error, because pbn writes that element. An element MAY be a data.frame, an atomic vector, a factor, a date,NULL, or a list of these to any depth.check_results()lists every allowed object. An element namedexclusionsMUST be the table of the exclusion steps, with the columnsstep,n_before,n_excludedandn_after. It MAY have zero rows.- d
The analysis data, or
NULL. You MUST gived. pbn stores only its number of rows. It then refuses a data.frame with that number of rows at any depth of the results. It also refuses a vector or a matrix with that number of values in one dimension. Gived = NULLwhen the run has no one table of the data.
Details
Call initialize_project() first. The results folder is the results
element that initialize_project() returns. It is
<home>/<version>_results/<scenario>/ for a scenario with 1 simulation,
and <home>/<version>_results/<scenario>/sim_<kkkk>/ otherwise.
The object is a named list. Its first element is manifest, and the
results follow in the order of the call. pbn builds the manifest, a
list with these elements:
pbn_versionandr_version.packages, a named character vector. The names are the attached and loaded packages that are not base packages, and the values are their versions.qs2is always in the list, because it writes the file.run_date, the date of the call asYYYY-MM-DD. It has no time, so two runs on one day with the same inputs and packages write the same bytes.version,scenario,sim,simsanddata_raw, frominitialize_project().data_rawis the data folder of the run.settings, the named list of the settings of the scenario from the setting columns ofCFG$scenarios. It is an empty list when there are none.source_md5, a named character vector for every scenario. It holds the md5 of<version>_run.Rand of each file in<version>_functions/, named by the path relative tohomeand sorted.initialize_project()computes it before it sources the files. Thecheck_results()rulemanifest_sourceneeds the run script in it, sosave_results()stops when<version>_run.Rdoes not exist.For the scenario
"real"only,data_md5, a named character vector with the md5 of each file directly indata_raw.initialize_project()computes it, so a file that the run writes after that call is not in the list.For a fake scenario only,
fake_md5, one string: the md5 of the code offake_<scenario>(), without its source references. Two runs of one simulation on one day with the same code and packages then write the same bytes. This holds also whenfake_<scenario>()stamps the time into a file. A change in a function thatfake_<scenario>()calls does not changefake_md5.n_rows_data, the number of rows ofd, orNAwhendisNULL.
See also
Other results:
check_results(),
read_results()
Examples
home <- file.path(tempdir(), "pbn_save_example")
dir.create(file.path(home, "v01_functions"), recursive = TRUE)
dir.create(file.path(home, "data"))
writeLines("# The run script.", file.path(home, "v01_run.R"))
writeLines(
"CFG <- list(scenarios = data.frame(scenario = 'real', sims = 1))",
file.path(home, "v01_functions", "_cfg.R")
)
pbn::initialize_project("v01", home, file.path(home, "data"), env = new.env())
#> You are NOT sourcing into .GlobalEnv. All functions will be sourced into an environment that is returned from this function.
#> Sourcing all code inside /tmp/RtmpOG2SVD/pbn_save_example/v01_functions into
pbn::save_results(
exclusions = data.frame(
step = "age 18 or more",
n_before = 100,
n_excluded = 4,
n_after = 96
),
estimates = data.frame(term = "x", estimate = 1.2),
counts = list(by_group = data.frame(grp = c("a", "b"), n = c(50, 46))),
p_interaction = 0.04,
d = NULL
)
names(pbn::read_results("v01", home = home))
#> [1] "manifest" "exclusions" "estimates" "counts"
#> [5] "p_interaction"
unlink(home, recursive = TRUE)
