sim.scenario {isobxr}

Simulate a scenario

Description

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:

1. fluxes
   (overwriting all or a subset of fluxes defined in 0_ISOBXR_MASTER.xlsx master file)

2. isotope fractionation coefficients
   (overwriting all or a subset of coefficients defined in 0_ISOBXR_MASTER.xlsx master file)

3. box sizes
   (overwriting all or a subset of box sizes defined in 0_ISOBXR_MASTER.xlsx master file)

4. rayleigh isotope distillation

5. isotope composition of a source box at initial state

Usage

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

1. single run results in SERIES directory: all single runs results as rds files

2. 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

## Not run: 
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")

## End(Not run)