Simulate a scenario — sim.scenario • isobxr

A function to compose an isotope box model scenario, defined by a series of successive runs,
each run inheriting from the final state conditions of the previous run.
It is possible to force parameters at each run, namely:

fluxes
(overwriting all or a subset of fluxes defined in 0_ISOBXR_MASTER.xlsx master file)
isotope fractionation coefficients
(overwriting all or a subset of coefficients defined in 0_ISOBXR_MASTER.xlsx master file)
box sizes
(overwriting all or a subset of box sizes defined in 0_ISOBXR_MASTER.xlsx master file)
rayleigh isotope distillation
isotope composition of a source box at initial state

sim.scenario(
  workdir,
  SERIES_ID,
  scenario_master_file,
  isobxr_master_file = "0_ISOBXR_MASTER",
  plot.hidden_boxes = NULL,
  plot.time_unit = NULL,
  export.single_run_digests = FALSE,
  export.data_as_csv_xlsx = FALSE,
  show.delta_plot = TRUE,
  save_outputs = FALSE,
  inspect_inputs = TRUE
)

Arguments

workdir: Working directory of isobxr excel master file and where output files will be stored if exported by user.
SERIES_ID: Name of the series the scenario run belongs to. It determines the folder in which the output files will be stored inside workdir.
scenario_master_file: Name of scenario excel master file.
isobxr_master_file: Name of isobxr excel master file.
Default is "0_ISOBXR_MASTER".
plot.hidden_boxes: list of box names (BOX_ID) to hide in scenario plot.
plot.time_unit: Time unit to use on plot if different from native time unit.
Character string, to be selected among the following:
micros, ms, s, min, h, d, wk, mo, yr, kyr, Myr, Gyr
Default is NULL.
export.single_run_digests: If TRUE, exports full digest of each single run of the scenario. Default is FALSE.
export.data_as_csv_xlsx: If TRUE, exports full scenario result data as csv and xlsx fo full to scenario digest directory.
Default is FALSE.
show.delta_plot: If TRUE, prints delta and size time evolution plots in R.
Default is TRUE.
save_outputs: If TRUE, saves all run outputs to local working directory (workdir).
By default, run outputs are stored in a temporary directory and erased if not saved.
Default is FALSE.
inspect_inputs: If TRUE, inspects and proof checks format of input taken from isobxr excel master file.
(Inspection run by read.isobxr_master function.)
Default is TRUE.

Value

Delta values and box sizes as a function of time.

sim.scenario outputs are saved to workdir if save_outputs = TRUE.

sim.scenario outputs consist of

single run results in SERIES directory: all single runs results as rds files
scenario digest in scenario DIGEST directory (SERIES/DIGEST):
1. isobxr master file archive as xlsx
2. scenario master file archive as xlsx
3. plot of delta and size vs. time as pdf
4. scenario results data set as rds, containing:
  1. delta_vs_t data frame of delta as a function of time
  2. size_vs_t data frame of box sizes as a function of time
  3. scenario_master list containing all inputs from scenario master file
  4. scenario_log data frame of scenario specific LOG excerpt
  5. isobxr_master list containing all inputs from isobxr master file
  6. paths list of scenario specific paths

Examples

if (FALSE) {
sim.scenario(workdir = "/Users/username/Documents/1_ABC_tutorial",
             SERIES_ID =  "1_source_change",
             scenario_master_file = "0_SCENARIO_source_change",
             isobxr_master_file = "0_ISOBXR_MASTER")
}