15  Package options

15.1 Overview

teems provides a set of advanced options that control package behavior across function calls. For example, teems is rather chatty and users may wish to silence all innocuous messages with ems_option_set(verbose = FALSE). Options are managed through three functions:

  • ems_option_get() retrieves current option values
  • ems_option_set() modifies option values
  • ems_option_reset() restores all options to their defaults
ems_option_get(
  name = NULL
)

ems_option_set(
  tempdir = NULL,
  verbose = NULL,
  ndigits = NULL,
  accuracy_threshold = NULL,
  accuracy_figures = NULL,
  accuracy_criterion = NULL,
  required_figures = NULL,
  full_exclude = NULL,
  check_shock_status = NULL,
  timestep_header = NULL,
  n_timestep_header = NULL,
  docker_tag = NULL,
  assertions = NULL,
  range_test_initial = NULL,
  range_test_updated = NULL,
  random_seed = NULL,
  refine = NULL,
  converge = NULL
)

ems_option_reset()

Options persist for the duration of the R session and are reset on package reload.

15.2 Retrieving options

View all current options:

ems_option_get()

Retrieve a specific option by name. An error is raised if the name is not a valid option:

ems_option_get("verbose")
ems_option_get("ndigits")

15.3 Setting options

One or more options can be set in a single call:

ems_option_set(verbose = FALSE)
ems_option_set(verbose = FALSE, ndigits = 8)

15.4 Resetting options

Reset all options to their default values:

ems_option_reset()

15.5 Available options

Option Default Description
tempdir tempdir() Directory used for temporary file storage during a model run
verbose TRUE If FALSE, function-specific diagnostics are silenced
ndigits 6 Number of digits to the right of the decimal point kept when data are written to file. Values smaller than 0.1 in magnitude keep ndigits significant digits instead, so small nonzero data (e.g. 1e-10) are not rounded to zero
accuracy_threshold 0.8 Share of results that must be accurate to at least accuracy_figures significant figures. A warning is generated if the share is lower
accuracy_figures 4 Significant figures, from 1 to 6, a result must reach to count as accurate
required_figures NULL Figures, from 1 to 6, at which a result gets the convergence code XRA in the accuracy summary. Reporting only
accuracy_criterion "solution" The accuracy summary judged: "solution" the levels values of the endogenous results, "data" the values read from data files and updated, "both" the two together. A run that updates no data is judged on the solution
full_exclude c("DREL", "DVER", "XXCR", "XXCD", "XXCP", "SLUG", "EFLG") Headers to fully exclude from all aspects of the model run. Failure to designate these headers properly will result in errors. Modify with caution
check_shock_status TRUE If FALSE, no check on shock element endogenous/exogenous status is conducted
timestep_header "YEAR" Header written with the time of each period, as given in time_steps of ems_data() (years, or steps from the initial period); the model uses the differences between periods as interval lengths. For novel intertemporal models — modify with caution
n_timestep_header "NTSP" Header written with the number of periods (the length of time_steps). For novel intertemporal models — modify with caution
docker_tag "latest" Tag of the teems image to solve with
assertions "fatal" Severity of TAB Assertion failures during ems_solve(): "fatal", "warn" or "off"
range_test_initial "fatal" Severity of declared-range violations (e.g. (ge 0)) on initial values, read or computed: "fatal", "warn" or "off"
range_test_updated "warn" As range_test_initial, for updated values
random_seed 1 Seed of the TAB function RANDOM(a,b). The same seed gives the same draws on every run; each Formula element keeps its draw across solution steps. Change the seed for a new sequence (GEMPACK instead draws a new sequence per run by default)
refine TRUE One refinement step after every "DBBD" linear solve, which brings its accuracy to that of "LU". It holds the system matrix through each solve, and the memory estimate counts it; FALSE turns it off. "LU" and "SBBD" are in practice as accurate as a single LU solve and are not refined; "NDBBD" is not refined, as it cannot yet keep its factorization for a second solve
converge FALSE TRUE applies GEMPACK’s treatment of poorly converging results to runs extrapolated from three solutions: the result with the most steps where the three do not converge cleanly, their average where they are nearly equal. Not available with subtotals