Package 'isobxr'

Title: Stable Isotope Box Modelling in R
Description: A set of functions to run simple and composite box-models to describe the dynamic or static distribution of stable isotopes in open or closed systems. The package also allows the sweeping of many parameters in both static and dynamic conditions. The mathematical models used in this package are derived from Albarede, 1995, Introduction to Geochemical Modelling, Cambridge University Press, Cambridge <doi:10.1017/CBO9780511622960>.
Authors: Theo Tacail [aut, cre]
Maintainer: Theo Tacail <[email protected]>
License: GPL-3
Version: 2.0.0.9000
Built: 2024-11-02 04:28:31 UTC
Source: https://github.com/ttacail/isobxr

Help Index

Fit n parameters to observations

Description

A function to find the combinations of values of n parameters producing final state delta values fitting within confidence intervals of observations.

Usage

fit.final_space(
  workdir,
  obs_file_name,
  sweep_space_digest_folders,
  fit_name = NULL,
  output_dir = NULL,
  delta_reference_box = NaN,
  excluded_boxes = NULL,
  print_correlogram = FALSE,
  print_lda = FALSE,
  print_LS_surfaces = FALSE,
  parameter_subsets = NULL,
  custom_expressions = NULL,
  save_outputs = FALSE,
  export_fit_data = 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)
obs_file_name

Name of csv file containing observations with csv extension.
Stored in workdir. Example: "observations.csv"
Should contain the following columns:

  1. BOX_ID: BOX ID (e.g., A, OCEAN...) as defined in isobxr master file.

  2. delta.def definition of delta value, e.g., d18O

  3. delta.ref BOX_ID of reservoir used as a reference.

  4. obs.delta average observed delta numerical value

  5. obs.CI confidence interval of delta value

  6. obs.CI.def definition of confidence interval, e.g., 95

  7. obs.file name of data source file

sweep_space_digest_folders

Name of sweep.final_nD digest directory.
Should start with "4_FINnD" and end with "_digest"
fit_name

Name given to specific fit. If NULL, output are named after date and time of fit.
output_dir

Destination directory for fit outputs. If NULL, outputs are stored in sweep_space_digest_folders directory. Default is NULL.
delta_reference_box

BOX ID of reference box, used to calculate difference between any box delta and reference box delta. Default is NaN.
delta_reference_box should match at least one of the values declared in the delta.ref column of observation csv file.
excluded_boxes

list of boxes to exclude from fit. Default is NULL.
print_correlogram

If TRUE, includes correlograms to final report when applicable.
Default is FALSE.

print_lda

If TRUE, includes linear discriminant analysis to final report when applicable.
Default is FALSE.
print_LS_surfaces

If TRUE, includes surfaces of least squarred residuals to final report when applicable.
Default is FALSE.
parameter_subsets

List of limits vectors for parameters to subset before fit.
For instance: list(swp.A.A_B = c(1, 1.00001)) to subset the swept fractionation factor from box A to B between 1 and 1.00001.
custom_expressions

Vector of expressions to add to the list of fitted parameters.
For instance: c("m0.A/f.A_B") to add the ratios of mass of A over A to B flux to the list of parameters.
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.
export_fit_data

If TRUE, exports fitted data as csv and rds files.

Value

A observation fit graphical report, in R session or exported as pdf, and a data report as R list or xlsx if required.

Merge results from all chunks of a given sweep.final_nD run

Description

Merge results from all chunks of a given sweep.final_nD run

Usage

merge_FINnD_chunks(workdir, FINnD_digest_dir.to_merge, save_outputs = 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)
FINnD_digest_dir.to_merge

Name of sweep.final_nD digest directory to which current chunks should be merged.
For instance: "4_FINnD_0_SWEEP_FINnD_demo_001_000_digest"
save_outputs

If TRUE, saves merged chunks outputs to sweep.final_nD digest directory.

Value

Merged chunks sweep.final_nD outputs, including results, chunk logs, chunked parameter spaces.

plot sweep.dyn_2D outputs

Description

A function to plot delta vs time from the sweep.dyn_2D runs

Usage

plot_dyn_2D(
  workdir,
  sweep_dir_name,
  time_unit = NULL,
  time_range = NULL,
  hidden_boxes = NULL,
  return_as_print = TRUE,
  free_y_scale = TRUE,
  swap_sweep_params = FALSE,
  show.delta_drift = FALSE,
  time_as_log10 = TRUE
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
sweep_dir_name

Full name of sweep.dyn_2D SERIES directory (character string)
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.
time_range

Time range to zoom on as vector of two values, such as: c(0,100)
Values in displayed time units.
Default is NULL.
hidden_boxes

List of boxes to hide from plots, as a vector of character strings.
For instance c("SOURCE", "SINK").
Default is NULL.
return_as_print

If TRUE, prints delta and size vs. time plots in a single page figure on R.
If FALSE, returns separately delta and size vs. time plots as list of editable R objects.
Default is TRUE.
free_y_scale

If TRUE, frees Y axis scale.
Default is TRUE.
swap_sweep_params

If TRUE, swaps the sweep parameter 1 and 2 representations from color to facet scales.
Default is FALSE.
show.delta_drift

If TRUE, displays drift of delta values from t0.
time_as_log10

If TRUE, uses logarithmic time scale in plot.
Default is TRUE.

Value

A set of plots showing the evolution of delta and sizes with time.

plot relaxation

Description

A function to plot the relaxation of isotope ratios in a system, including characteristic times

Usage

plot_relaxation(
  workdir,
  flux_list,
  coeff_list,
  spiked_boxes,
  spike.max_delta = 100,
  n_steps = 10000,
  hidden_boxes = NULL,
  show.residence_time = TRUE,
  show.facets = FALSE,
  time_landmarks = NULL,
  time_as_log10 = TRUE,
  isobxr_master_file = "0_ISOBXR_MASTER",
  time.resolution_cut = NULL
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
flux_list

Name of the list of fluxes and initial box sizes to be used for the run,
calling (by its header name) a single column of the FLUXES sheet of the isobxr excel master file.
(character string)
coeff_list

Name of the list of fractionation coefficients to be used for the run,
calling (by its header name) a single column of the COEFFS sheet of the isobxr excel master file.
(character string)
spiked_boxes

Vector of box names ("BOX_ID") to be spiked.
If several boxes are listed, initial spike will be evenly distributed from 0 to spike.max_delta value.
spike.max_delta

Value of the maximum spike isotope composition
(in permil on the delta scale).
Default is 100 permil.
n_steps

Number of calculation steps. Determines the resolution of the run.
Default is 10000.
hidden_boxes

Vector of boxes to hide from plots.
For instance c("SOURCE", "SINK").
Default is NULL.
show.residence_time

If TRUE, displays box-specific residence times on plot.
Default is FALSE.
show.facets

If TRUE, displays results in box-specific facets.
Default is FALSE.
time_landmarks

Vector of time landmarks to display on x-axis (numerical values).
time_as_log10

If TRUE, uses logarithmic time scale in plot.
Default is TRUE.
isobxr_master_file

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

Time below which resolution is increased. Default is NULL.

Value

A plots showing the evolution of the isotopic ratios in the system until full relaxation,
defined as the maximum relaxation time multiplied by 10.

Examples

## Not run: 
plot_relaxation(workdir = "/Users/username/Documents/1_ABC_tutorial",
                flux_list = "Fx6_ABC_open_bal",
                coeff_list = "a0",
                n_steps = 1000,
                spiked_boxes = c("SOURCE"))

## End(Not run)

plot sim.scenario outputs

Description

A function to plot delta and size vs time from the sim.scenario runs and to include observations along simulations.

Usage

plot_scenario(
  workdir,
  scenario_dir_name,
  shown_runs = NULL,
  time_unit = NULL,
  hidden_boxes = NULL,
  return_as_print = TRUE,
  show.facets = FALSE,
  show.run_separations = TRUE,
  observations_file = NULL,
  observations_groups = NULL
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
scenario_dir_name

name of sim.scenario SERIES directory (starts with 3_SCEN)
shown_runs

Vector of successive run numbers (RUN_n) to be displayed (e.g., 1:5).
Default is run 2 to last run (hides initial relaxation run)
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.
hidden_boxes

List of boxes to hide from plots, as a vector of character strings.
For instance c("SOURCE", "SINK").
return_as_print

If TRUE, prints delta and size vs. time plots in a single page figure on R.
If FALSE, returns separately delta and size vs. time plots as list of two editable R objects.
show.facets

If TRUE, shows delta vs. time as faceted by BOX.
Default is FALSE.
show.run_separations

If TRUE, shows limits between subruns.
Default is TRUE.
observations_file

Name of the csv file containing observations (without csv extension).
Observation csv file should contain the following columns:

  1. GROUP: observation subset group label if relevant

  2. BOX_ID: BOX ID (e.g., A, OCEAN...) as defined in isobxr master file.

  3. delta.def definition of delta value, e.g., d18O

  4. obs.delta average observed delta numerical value

  5. obs.CI confidence interval of delta value

  6. obs.CI.def definition of confidence interval, e.g., 95

  7. obs.counts number of observations corresponding to average delta

  8. Time time of observation in scenario timeline, in display time units

Default is NULL.
observations_groups

vector of observations groups to include in plot,
from GROUP column in observation csv file.
Default is NULL.

Value

A set of plots showing the evolution of delta and sizes with time.

plot sim.single_run outputs

Description

A function to plot delta and size vs time from the sim.single_run outputs

Usage

plot_single_run(
  workdir,
  RUN_ID,
  time_as_log10 = TRUE,
  time_unit = NULL,
  hidden_boxes = NULL,
  return_as_print = TRUE
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
RUN_ID

ID of the run (formerly SERIES_RUN_ID). Corresponds to the name of the .rds file storing the results of the run.
time_as_log10

If TRUE, uses logarithmic time scale in plot.
Default is TRUE.
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.
hidden_boxes

List of boxes to hide from plots, as a vector of character strings.
For instance c("SOURCE", "SINK").
return_as_print

If TRUE, prints delta and size vs. time plots in a single page figure on R.
If FALSE, returns separately delta and size vs. time plots as list of editable R objects.
Default is TRUE.

Value

A set of plots showing the evolution of delta and sizes with time.

Read and inspect sweep.dyn_2D master files

Description

A function to read and inspect the sweep.dyn_2D master files and obtain a master formatted list.

Usage

read.dyn_2D_master(workdir, dyn_2D_master_file, isobxr_master_file)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
dyn_2D_master_file

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

Name of isobxr excel master file. (without file "xlsx" extension). Default is "0_ISOBXR_MASTER".

Value

List of formatted dyn_2D_master_file master inputs.

Examples

read.dyn_2D_master(workdir = "/Users/username/Documents/1_ABC_tutorial",
                   dyn_2D_master_file = "0_SWEEP_DYN_demo",
                   isobxr_master_file = "0_ISOBXR_MASTER")

Read and inspect sweep.final_nD master files

Description

A function to read and inspect the sweep.final_nD master files and obtain a master formatted list.

Usage

read.final_nD_master(workdir, final_nD_master_file, isobxr_master_file)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
final_nD_master_file

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

Name of isobxr excel master file. (without file "xlsx" extension). Default is "0_ISOBXR_MASTER".

Details

List contains:

  1. param_space data frame of shuffled all combinations of all parameters values.

  2. sweep.DEFAULT data frame of default run conditions
    (flux and coeff lists, t_max, chunk size)

  3. sweep_lists_ids list of names of swept parameters

Value

List of formatted sweep.final_nD master inputs

Examples

read.final_nD_master(workdir = "/Users/username/Documents/1_ABC_tutorial",
                     final_nD_master_file = "0_SWEEP_FINnD_demo",
                     isobxr_master_file = "0_ISOBXR_MASTER")

Read and inspect isobxr master files

Description

A function to read and inspect the isobxr master files and obtain a master formatted list.

Usage

read.isobxr_master(
  workdir,
  isobxr_master_file = "0_ISOBXR_MASTER",
  inspect = TRUE,
  export_rds = FALSE
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
isobxr_master_file

Name of isobxr excel master file. (without file "xlsx" extension). Default is "0_ISOBXR_MASTER".
inspect

If TRUE, checks all inputs from isobxr master file for format and structure errors.
Default is TRUE.
export_rds

If TRUE, exports rds version of isobxr master file to working directory.
Default is FALSE.

Value

A formatted list of data frames containing constants, box, fluxes and fractionation coefficients descriptions.

Examples

read.isobxr_master(workdir = "/Users/username/Documents/1_ABC_tutorial",
                   isobxr_master_file = "0_ISOBXR_MASTER",
                   export_rds = FALSE,
                   inspect = TRUE)

Read and inspect scenario master files

Description

A function to read and inspect the scenario master files and obtain a master formatted list.

Usage

read.scenario_master(
  workdir,
  scenario_master_file,
  isobxr_master_file = "0_ISOBXR_MASTER"
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
scenario_master_file

Name of scenario excel master file. (without file "xlsx" extension).
isobxr_master_file

Name of isobxr excel master file. (without file "xlsx" extension). Default is "0_ISOBXR_MASTER".

Value

List of formatted scenario master inputs.

Examples

read.scenario_master(workdir = "/Users/username/Documents/1_ABC_tutorial",
                     scenario_master_file = "0_SCENARIO_source_change",
                     isobxr_master_file = "0_ISOBXR_MASTER")

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)

Run a single isotope box-model simulation

Description

A function to run the isobxr stable isotope box model, assessing the design of the model and automatically running solve_numerically or solve_analytically depending on system design.

Usage

sim.single_run(
  workdir,
  SERIES_ID,
  flux_list,
  coeff_list,
  t_max,
  n_steps,
  isobxr_master_file = "0_ISOBXR_MASTER",
  suppress_messages = FALSE,
  export.diagrams = FALSE,
  export.delta_plot = FALSE,
  export.data_as_csv_xlsx = FALSE,
  plot.time_as_log10 = TRUE,
  plot.time_unit = NULL,
  show.delta_plot = TRUE,
  inspect_inputs = TRUE,
  save_outputs = FALSE,
  return_data = FALSE,
  solver = "auto",
  n_zeros_RUN_IDs = 4,
  FORCING_RAYLEIGH = NULL,
  FORCING_SIZE = NULL,
  FORCING_DELTA = NULL,
  FORCING_ALPHA = NULL,
  COMPOSITE = FALSE,
  COMPO_SERIES_n = NaN,
  COMPO_SERIES_FAMILY = NaN,
  EXPLORER = FALSE,
  EXPLO_SERIES_n = NaN,
  EXPLO_SERIES_FAMILY = NaN,
  isobxr_master = NULL,
  diagram_pdf.widh_height = NULL
)

Arguments

workdir

Working directory of isobxr excel master file and where output files will be stored if exported by user. (character string)
SERIES_ID

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

Name of the list of fluxes and initial box sizes to be used for the run,
calling (by its header name) a single column of the FLUXES sheet of the isobxr excel master file.
(character string)
coeff_list

Name of the list of fractionation coefficients to be used for the run,
calling (by its header name) a single column of the COEFFS sheet of the isobxr excel master file.
(character string)
t_max

Run duration, given in the same time units as unit declared in CONSTANTS
spreadsheet of isobxr excel master file in the TIME_UNIT column. (integer)
n_steps

Number of calculation steps.
It determines the resolution of the run.
(integer)
isobxr_master_file

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

If TRUE, hides all information and warning messages regarding run.
Default is FALSE.
export.diagrams

If TRUE, exports box-model flux and fractionation diagrams as pdf.
Default is FALSE.
export.delta_plot

If TRUE, exports delta and size time evolution plots of the evolution of the system, as pdf.
Default is FALSE.
export.data_as_csv_xlsx

If TRUE, exports all results and run conditions as csv and xlsx files,
to DIGEST directory.
Default is FALSE.
plot.time_as_log10

If TRUE, uses logarithmic time scale in plot.
Default is FALSE.
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.
show.delta_plot

If TRUE, prints delta and size time evolution plots in R. Default is TRUE.
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.
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.
return_data

If TRUE, returns all data (inputs and outputs) as a list.
Default is FALSE.
solver

Determines what solver to used: "analytical" or "numerical".
Default is "auto" for automatic selection of adapted solver. Note that this option returns warnings or prevents user to run when solver wished is not adapted to system solution.
n_zeros_RUN_IDs

Number of figures used in iteration of RUNs of a given series (SERIES_ID).
Default is 4: the run IDs of a given series range between 0001 and 9999.
FORCING_RAYLEIGH

OPTIONAL
Dataframe describing the forcing on a fractionation coefficient by a Rayleigh isotope distillation,
as a function of flux intensities and a fundamental fractionation coefficient.
Dataframe formatting details are in isobxr vignette.
Default is NULL.
FORCING_SIZE

OPTIONAL
Dataframe describing the forcing on one or several box sizes (mass of element X).
The newly defined sizes for the given set of boxes overwrite their sizes as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.
FORCING_DELTA

OPTIONAL
Dataframe describing the forcing on one or several boxes initial isotope composition expressed as delta values.
The newly defined delta values for the given set of boxes overwrite the delta values as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.
FORCING_ALPHA

OPTIONAL
Dataframe describing the forcing on one or several fractionation coefficients from one reservoir to another.
The newly defined alpha values for the given set of boxes overwrite the alpha values as previously defined in isobxr excel master file.
Dataframe formatting details are in isobxr vignette.
Default is NULL.
COMPOSITE

NOT TO BE USED IN SINGLE RUN
Logical value automatically defined in sim.scenario.
Default is FALSE.
COMPO_SERIES_n

NOT TO BE USED IN SINGLE RUN
Iteration of the composite run for the given series it belongs to, automatically defined in sim.scenario.
Default is NaN.
COMPO_SERIES_FAMILY

NOT TO BE USED IN SINGLE RUN
Composite run series family, automatically defined in sim.scenario.
Default is NaN.
EXPLORER

NOT TO BE USED IN SINGLE RUN
Logical value automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is FALSE.
EXPLO_SERIES_n

NOT TO BE USED IN SINGLE RUN
Iteration of the sweep run for the given series it belongs to, automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is NaN.
EXPLO_SERIES_FAMILY

NOT TO BE USED IN SINGLE RUN
Sweep run series family, automatically defined in sweep.final_nD or sweep.dyn_2D.
Default is NaN.
isobxr_master

isobxr_master list of input dataframes formatted by read.isobxr_master
Overwrites isobxr_master_file. Default is NULL.
diagram_pdf.widh_height

Vector of width and height in inches of the pdf diagrams.

Value

A results data set as a list containing the following components:

  1. inputs input data:

    1. CONSTS data frame of all run specific constants.

    2. INITIAL data frame of delta and sizes at t = 0 in all boxes.

    3. FLUXES data frame of all fluxes intensities (row ID: FROM / col ID: TO)

    4. COEFFS data frame of all fractionation coefficient values (row ID: FROM / col ID: TO)

    5. BOX_META data frame of box specific metadata (e.g., flux balance, residence times, layout position )

    6. bx.groups list of box names grouped by relevant categories (e.g., disconnected boxes, infinite boxes)

    7. LOG data frame of run specific LOG excerpt.

  2. outputs output data:

    1. solver

    2. final_state

    3. delta_vs_t

    4. size_vs_t

    5. for analytical solutions

      1. diffeq_solutions solutions of differential equations,
        including relaxation times, eigenvalues, constants, eigenvectors

  3. paths list of run specific paths

Examples

## Not run: 
sim.single_run(workdir = "/Users/username/Documents/1_ABC_tutorial",
               SERIES_ID = "1_ABC_balanced_closed",
               flux_list = "Fx1_ABC_bal",
               coeff_list = "a1",
               t_max = 2500,
               n_steps = 2500)

## End(Not run)

Analytically solve stable isotope box models

Description

An analytical solver of the system of ordinary differential
equations (ODES) of stable isotope ratios of element X in all boxes.
Not intended for manual use.
The analytical solver finds the eigenvalues and eigenvectors of the ODES.
It determines the set of analytical solutions that describes the evolution of isotope ratios in each box over time.

Usage

solve_analytically(IN, paths, to_DIGEST_csv = FALSE, return_results = FALSE)

Arguments

IN

input data, edited by sim.single_run (list of dataframes)
paths

paths object edited by sim.single_run (list of characters)
to_DIGEST_csv

if TRUE, edits csv outputs to DIGEST directory
Default is FALSE.
return_results

if TRUE, results returned as a list of R objects.
Default is FALSE.

Value

Analytically determined evolution of stable isotope compositions in all boxes over the run duration as specified in INPUT file.

Run outputs are stored in a temporary directory and not exported by solve_numerically.

The outputs of the run are stored in the rds output file in the SERIES directory with the following file name structure:
SERIES_ID + RUN_n.rds

Optional csv outputs to the DIGEST folder are as follows

  1. OUT data file with initial and final size and delta values in all boxes.
    (file name structure: out_1_A_OUT + SERIES_ID + RUN_n + .csv)

  2. ODE_SOLNs data file summarizing outputs of the analytical solutions of the ODES
    (eigenvalues, eigenvectors, relaxation times, constants according to initial conditions).
    (file name structure: out_2_A_ODE_SOLNs + SERIES_ID + RUN_n + .csv)

  3. evD data file of the evolution with time of the delta values in all boxes.
    (file name structure: out_3_A_evD + SERIES_ID + RUN_n + .csv)

Numerically solve stable isotope box models

Description

A numerical solver of the system of ordinary differential equations (ODES),
describing the evolution of stable isotope ratios in all boxes of a system.
Not intended for manual use.
The numerical solver uses the deSolve::ode function to integrate the stable isotopes ratios over time in each box. It allows the calculation of the evolution of stable isotope ratio in the case of unbalanced outward and inward fluxes of element X in a given box resulting in the accumulation or loss of element X.

Usage

solve_numerically(IN, paths, to_DIGEST_csv = FALSE, return_results = FALSE)

Arguments

IN

input data, edited by sim.single_run (list of dataframes)
paths

paths object edited by sim.single_run (list of characters)
to_DIGEST_csv

if TRUE, edits csv outputs to DIGEST directory
Default is FALSE.
return_results

if TRUE, results returned as a list of R objects.
Default is FALSE.

Value

Numerically determined evolution of stable isotope compositions
and masses of element X in all boxes over the run duration as specified in INPUT file.

Run outputs are stored in a temporary directory and not exported by solve_numerically.

The outputs of the run are stored in the rds output file in the SERIES directory with the following file name structure:
SERIES_ID + RUN_n.rds

Optional csv outputs to DIGEST directory are as follows

  1. OUT data file storing initial and final size and delta values in all boxes.
    (file name structure: out_1_N_OUT + RUN name + .csv)

  2. evS data file storing the evolution with time of the sizes (masses of element X) of all boxes.
    (file name structure: out_2_N_evS + RUN name + .csv)

  3. evD data file storing the evolution with time of the delta values in all boxes.
    (file name structure: out_3_N_evD + RUN name + .csv)

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

Description

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.

Usage

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

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

## End(Not run)

Sweep the space of n parameters at the final state of a system

Description

A function to assess the influence of n parameters (varying over a range of values) on the final state of a system.

Usage

sweep.final_nD(
  workdir,
  sweep_master_file,
  sweep_dir_to_complete = NULL,
  export.data_as_csv_xlsx = FALSE,
  isobxr_master_file = "0_ISOBXR_MASTER",
  save_outputs = 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)
sweep_master_file

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

Name of directory of previously halted sweep.final_nD run that the user wishes to continue. Starts with "4_FINnD".
Default is NULL.
export.data_as_csv_xlsx

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

Name of isobxr excel master file.
Default is "0_ISOBXR_MASTER".
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.

Value

Delta values and box sizes at final state of the system, in the n-dimensions space of parameters. sweep.final_nD outputs are saved to workdir if save_outputs = TRUE.

sweep.final_nD outputs

  1. digest sweep.final_nD outputs full sweep.final_nD outputs are stored in a digest directory directly in workdir:

    1. isobxr master file archive as xlsx

    2. global chunk_log as csv

    3. global chunk_log as rds

    4. sweep.final_nD master file archive as xlsx

    5. sweep.final_nD merged chunks LOG excerpt as csv

    6. sweep.final_nD merged param_space, current progress, as rds (space of swept parameters)

    7. sweep.final_nD merged results, current progress, as rds

      1. data frame containing delta and size at final state across whole n-dimensions space of parameters

      2. sweep.final_nD param_space as planned, as rds

      3. sweep.final_nD sweep_default data frame of default run conditions, as rds

      4. sweep.final_nD sweep progress plot as pdf, follows merging of chunks

  2. chunks sweep.final_nD outputs chunk directories are edited in case total number. of runs exceeds chunk size defined in sweep.final_nD master file. They are removed after full sweep.