Sweep the space of two parameters during the response to a perturbation

Source: R/sweep_dyn_2D.R

A function to assess the influence of two parameters (varying over a range of values) on dynamic evolution of a system in response to a given perturbation.

sweep.dyn_2D(
  workdir,
  SERIES_ID,
  plot.time_unit = NULL,
  isobxr_master_file = "0_ISOBXR_MASTER",
  sweep_master_file,
  swept_param_1,
  swept_param_2,
  export.data_as_csv_xlsx = TRUE,
  show.delta_plot = TRUE,
  save_outputs = FALSE,
  ask_confirmation = TRUE,
  keep_single_run_rds = FALSE
)

Arguments

workdir

Working directory of 0_ISOBXR_MASTER.xlsx master file,
of the dynamic sweep master file (e.g., 0_EXPLO_DYN_MASTER.xlsx)
and where output files will be stored if saved by user.
(character string)

SERIES_ID

Name of the sweep series belongs to.
It determines the folder in which the output files will be stored inside workdir.
(character string)

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.

isobxr_master_file

Name of isobxr excel master file.
Default is "0_ISOBXR_MASTER".

sweep_master_file

Name of sweep.dyn_2D excel master file. (without file "xlsx" extension).

swept_param_1

Set of values of sweeping parameter 1.
Formatted data frame, see vignette for further details.

swept_param_2

Set of values of sweeping parameter 2.
Formatted data frame, see vignette for further details.

export.data_as_csv_xlsx

If TRUE, exports full sweep result data as csv and xlsx fo full to sweep digest directory.
Default is TRUE.

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.

ask_confirmation

If TRUE, asks confirmation to run in interactive sessions.
Default is TRUE.

keep_single_run_rds

If TRUE, keeps single runs outputs (rds files in SERIES directory).
Default is FALSE.

Value

Delta values and box sizes as a function of time in response to a perturbation, in a 2D space of parameters sweep.dyn_2D outputs are saved to workdir if save_outputs = TRUE.

sweep.dyn_2D outputs consist of

  1. single run results in SERIES directory: all single runs results as rds files
    (keep_single_run_rds = TRUE)

  2. sweep digest in sweep DIGEST directory (SERIES/DIGEST):

    1. isobxr master file archive as xlsx (export.data_as_csv_xlsx = TRUE)

    2. sweep.dyn_2D master file archive as xlsx (export.data_as_csv_xlsx = TRUE)

    3. sweep.dyn_2D LOG excerpt as csv (export.data_as_csv_xlsx = TRUE)

    4. delta_size_vs_t csv of delta and size vs time in 2D space (export.data_as_csv_xlsx = TRUE)

    5. plot of delta and size vs. time in 2D space as pdf

    6. sweep.dyn_2D results data set as rds, containing:

      1. delta_size_vs_t data frame of delta and size as a function of time

      2. sweeep_master list containing all inputs from sweep master file

      3. sweep_log data frame of sweep specific LOG excerpt

      4. isobxr_master list containing all inputs from isobxr master file

      5. paths list of sweep specific paths

Examples

if (FALSE) {
sweep.dyn_2D(workdir = "/Users/username/Documents/1_ABC_tutorial",
             SERIES_ID = "sweep_dyn_test",
             isobxr_master_file = "0_ISOBXR_MASTER",
             sweep_master_file = "0_SWEEP_DYN_demo",
             swept_param_1 = data.frame(FROM = c("A"),
                                        TO = c("C"),
                                        ALPHA_MIN = 0.999,
                                        ALPHA_MAX = 1,
                                        ALPHA_STEPS = 0.0005,
                                        EXPLO_TYPES = "EXPLO_1_ALPHA"),
             swept_param_2 = data.frame(BOX_ID = c("B"),
                                        SIZE_MIN = 2100,
                                        SIZE_MAX = 3000,
                                        SIZE_STEPS = 300,
                                        EXPLO_TYPES = "EXPLO_1_SIZE"),
             ask_confirmation = FALSE)
}