
Start one scenario of an analysis project version
Source:R/initialize_project.R
initialize_project.Rdinitialize_project() sets up one simulation of one scenario of a project
version, and sources the functions folder of that version. It MUST be the
first call in every vNN_run.R.
Arguments
- version
The version, written as
"v"and two digits, for example"v01".- home
The project folder. It holds
<version>_run.Rand<version>_functions/.- data_raw
The folder of the real raw data. It MUST exist when the scenario is
"real". pbn does not read it for any other scenario.- env
The environment that the functions folder is sourced into.
Value
Invisibly, a list with version, home, scenario, sim,
sims, results, data_raw and settings. results is the results
folder and data_raw is the data folder of the run. settings is a
named list of the settings of the scenario, or an empty list when
CFG$scenarios has no setting column.
Details
_cfg.R in <version>_functions/ MUST set CFG$scenarios, a data.frame
with these columns:
scenario: unique names that match^[a-z0-9_]+$. One name MUST be"real".sims: the number of simulations of the scenario, a whole number of 1 or more.
Each other column is a setting of the scenario, for example n_boot for a
number of bootstrap replicates that is smaller in the fake scenarios. A
setting column MUST be an atomic vector with no NA. A list column or an
NA stops initialize_project() and run_scenarios(), and the error
names the column. p$settings holds the value of each setting column for
the scenario of the run. save_results() stores the settings as
CFG$scenarios gives them in manifest$settings. A change that the run
script makes to p$settings does not reach the manifest.
The scenario and the simulation come from the first of these that gives them. pbn reads no environment variables.
The trailing command-line arguments
scenario=<name>andsim=<k>.run_scenarios()gives both. When only one of them is there, the other one is"real"or 1.The choice of
use_scenario(), for a person who steps through the script by hand.The scenario
"real"and the simulation 1.
The choice of use_scenario() lasts for the R session.
In an interactive R session, initialize_project() prints one line, for
example pbn: scenario null, simulation 2 of 3 (fake). (fake) is there
for each scenario other than "real".
initialize_project() does these steps in this order:
It computes the md5 of
<version>_run.Rand of each file in<version>_functions/, before it sources them.save_results()stores them inmanifest$source_md5, andrun_scenarios(resume = TRUE)reads them.It calls
org::initialize_project()withresultsset to<home>/<version>_results,results_subfolderset to the scenario,folders_to_be_sourcedset to<version>_functions, andmax_loc_per_fileset to 1000.It reads
CFG$scenarios. The results folder is<version>_results/<scenario>/when the scenario has 1 simulation, and<version>_results/<scenario>/sim_<kkkk>/otherwise.<kkkk>is the simulation with four digits.org::project$results_todayis set to this folder.It calls
set.seed(sim). It also callsset.seed(sim)before step 2, so random work while org sources the functions folder depends onsimonly.For
"real", the data folder isdata_raw. For any other scenario, the data folder isdata/in the results folder.initialize_project()deletes it, creates it empty, and callsfake_<scenario>(dir)with its path. The project MUST definefake_<scenario>()in<version>_functions/.It computes an md5 that identifies the data, and
save_results()stores it in the manifest:For
"real", the md5 of each file directly in the data folder, asmanifest$data_md5. A file that the run writes later is not in the list.For a fake scenario, the md5 of the code of
fake_<scenario>(), asmanifest$fake_md5. A writer such ashaven::write_sav()stamps the time into the file. The md5 of the files would then change on every run, and the data would not.
initialize_project() stops in these cases:
scenario=orsim=is given more than once.sim=is not a whole number of 1 or more.The scenario is not in
CFG$scenarios, orsimis more than itssims.fake_<scenario>()is missing.A setting column of
CFG$scenariosis a list or hasNA.
When it stops, it deletes each empty results folder that the call created.
The state of the run is then empty, so save_results() and
end_if_fake_scenario() stop until a call succeeds. The choice of
use_scenario() stays. It never creates a folder with today's date.
See also
Other project setup:
end_if_fake_scenario(),
run_scenarios(),
use_scenario()
Examples
home <- file.path(tempdir(), "pbn_initialize_example")
dir.create(file.path(home, "v01_functions"), recursive = TRUE)
dir.create(file.path(home, "data"))
writeLines(
c(
"CFG <- list(",
" scenarios = data.frame(scenario = c('real', 'null'), sims = c(1, 3))",
")",
"fake_null <- function(dir) {",
" utils::write.csv(data.frame(x = rnorm(5)), file.path(dir, 'd.csv'))",
"}"
),
file.path(home, "v01_functions", "_cfg.R")
)
utils::write.csv(data.frame(x = 1:5), file.path(home, "data", "d.csv"))
env <- new.env()
p <- pbn::initialize_project(
version = "v01",
home = home,
data_raw = file.path(home, "data"),
env = 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_initialize_example/v01_functions into
p$scenario
#> [1] "real"
p$results
#> [1] "/tmp/RtmpOG2SVD/pbn_initialize_example/v01_results/real"
list.files(p$data_raw)
#> [1] "d.csv"
unlink(home, recursive = TRUE)