7 Loading models

7.1 Overview

The ems_model() function loads the model and its closure, conducts pre-deployment checks, determines temporal dynamics, and allows for the loading of aggregated coefficient data. The output of this function is a tibble with attributes containing the parsed model input and is a required input to the "model" argument of the ems_deploy() function.

ems_model(model_file, closure_file, var_omit = NULL, ...)

Argument	Type	Description
`model_file`	Character	File name in working directory or path to a `.tab` file
`closure_file`	Character	File name in working directory or path to a `.cls` closure file
`var_omit`	Character vector or `NULL`	Variables to substitute with `0` and remove from closure
`...`	Named arguments	Coefficient value injections (numeric, data frame, or CSV path)

Both model_file and closure_file are required arguments.

8 The model file

Model input in teems is currently limited to Tablo (.tab) files. Vetted models and their closures are available at teems-models.

Model	Files	Description
GTAPv6	`GTAPv6.tab`, `GTAPv6.cls`	GTAP version 6.2 format
GTAPv7	`GTAPv7.tab`, `GTAPv7.cls`	GTAP version 7.0 format
GTAP_INT	`GTAP_INT.tab`, `GTAP_INT.cls`	GTAP intertemporal
GTAP_RE	`GTAP_RE.tab`, `GTAP_RE.cls`	GTAP rational expectations

Users may load their own models by providing a path to a Tablo file and closure:

model <- ems_model(
  model_file = "path/to/custom_model.tab",
  closure_file = "path/to/custom_model.cls"
)

We recommend that users seeking to load custom models first review the formatting of the vetted models at teems-models in order to make any necessary modifications for use within the teems software ecosystem. In some cases it may be easiest to use existing compatible models as a starting point for modifications. Although the teems-solver does not support all current GEMPack declarations, there is usually a workaround. Running a diff on the original GTAP models and those in teems-models is a good starting point for understanding potential incompatibilities.

8.1 Closure selection

Standard model-specific closures are available within the model repository: teems-models. The general format consists of:

exogenous
A \n delimited list of exogenous variables
;
rest exogenous
;

8.2 Incompatible features

The teems-solver was originally designed as a GEMPack emulator and we have no intention of attempting to reproduce the very thorough GEMPack documentation on the Tablo scripting language and underlying solution software. Most Tablo model files (.tab) that work with GEMPack will also work with the teems-solver with some minor modifications. There are however a range of newer GEMPack features that are not compatible and are not likely to be incorporated. Fortunately there are workarounds for the vast majority as described below.

Considerable efforts have been made to correctly parse Tablo files but it is likely that custom Tablo files will need to be modified. If you find an incompatibility not listed here and feel that it should be addressed, please feel free to contact us with your model file. Some of the more frequent incompatibilities and workarounds are listed here.

8.2.1 Supported Tablo statements

The parser recognizes the following Tablo statements: File, Coefficient, Read, Update, Set, Subset, Formula, Assertion, Variable, Equation, Write, and Zerodivide. Statements not in this list are either unsupported (e.g., Omit, raising an error) or ignored (Postsim, raising a warning).

8.2.2 Set and subset declarations

Multiple + or - operators within a single declaration are not supported. Instead of

Set A123 = A1 + A2 + A3;

Use

Set A12 = A1 + A1;
Set A123 = A12 + A3;

Identical set assignment without a Read statement is not supported. Instead of

Set A # example set A # maximum size 5 read elements from file GTAPSETS header "H2";
Set B # example set # = Set A;

Use

Set A # example set A # maximum size 5 read elements from file GTAPSETS header "H2";
Set B # example set B # maximum size 5 read elements from file GTAPSETS header "H2";

Binary set switches using a colon within a Set definition is not supported. The SLUG coefficient is not used to identify sluggish endowments. Declare these sets explicitly or via set operations.

Instead of

Set ENDWM # mobile endowments # = (all,e,ENDW:ENDOWFLAG(e,"mobile") ne 0);

Declare sets explicitly within the Tablo file:

Set ENDWM # mobile endowment # (capital, unsklab, sklab);

Note that sets in the full form (all elements) and subsetted form (model-specific aggregations) can be loaded using ... with ems_model() and type = "set" with ems_aux().

Capital goods The CGDS sector in v6.2 format models is renamed to zcgds by default due to R data.table C-locale sorting and preference for all set elements to be lowercase.

8.2.3 Formulas and Equations

No IF statements in Formula or Equation RHS (use sets). Instead of

Formula (all,c,COMM)(all,r,REG)
    VCB(c,r) = VDB(c,r) + sum{d,REG, VXSB(c,r,d)} + IF[c in MARG, VST(c,r)];

Use

Formula (all,c,MARG)(all,r,REG)
    VCB(c,r) = VDB(c,r) + sum{d,REG, VXSB(c,r,d)} + VST(c,r);
Formula (all,c,NMRG)(all,r,REG)
    VCB(c,r) = VDB(c,r) + sum{d,REG, VXSB(c,r,d)};

8.3 Variable omissions

Variables specified with var_omit will be removed from the model closure and replaced with 0 within the model file. If a variable designated for omission is not found in the model, an error is raised.

Standard v7.0 data format variable omissions: c("atall", "avaall", "tfe", "tfm", "tgd", "tgm", "tid", "tim") Standard v6.2 data format variable omissions: c("atall", "tfd", "avaall", "tf", "tfm", "tgd", "tgm", "tpd", "tpm")

8.4 Coefficient value injection

The ... argument in ems_model() allows users to assign aggregation-specific values to model coefficients. This is used to inject modified values into existing coefficients as well as provide data to new coefficients (aggregated). All data inputted here must be model-aggregation specific and will not be subject to aggregation. For loading disaggregated data, see ems_aux() and ems_data(). The left-hand side (name) must correspond to a coefficient (not header) declared within the model input. Three input types are supported, with model “Read” and “Formula” declarations modified accordingly:

8.4.1 Uniform numeric value

A single numeric value can be assigned to a coefficient. All set combinations for that coefficient will receive this uniform value.

model <- ems_model(
  model_file = ems_example("GTAP_RE.tab"),
  closure_file = ems_example("GTAP_RE.cls"),
  KAPPA = 0.54321
)

Providing a numeric vector of length greater than 1 will raise an error. Instead here use a data frame with the appropriate sets to assign multiple heterogeneous values to a coefficient.

8.4.2 Data frame

A data frame (or data frame extension such as tibble or data.table) can be used to assign heterogeneous values across set combinations. The data frame must contain columns for each set index using the model-specific naming convention (set name + variable index, e.g., REGr, COMMc, ALLTIMEt) and a Value column.

# Heterogeneous values for SUBPAR coefficient (Read-type)
COMMc <- c("crops", "food", "livestock", "mnfcs", "svces")
REGr <- c("usa", "chn", "row")
ALLTIMEt <- seq(0, 10)

SUBPAR <- expand.grid(
  COMMc = COMMc,
  REGr = REGr,
  ALLTIMEt = ALLTIMEt
)

SUBPAR$Value <- runif(nrow(SUBPAR))

model <- ems_model(
  model_file = ems_example("GTAP_RE.tab"),
  closure_file = ems_example("GTAP_RE.cls"),
  SUBPAR = SUBPAR
)

This works for both Read-type and Formula-type coefficients:

# Heterogeneous values for CPHI coefficient (Formula-type)
REGr <- c("usa", "chn", "row")
ALLTIMEt <- seq(0, 10)

CPHI <- expand.grid(
  REGr = REGr,
  ALLTIMEt = ALLTIMEt
)
CPHI$Value <- runif(nrow(CPHI))

model <- ems_model(
  model_file = ems_example("GTAP_RE.tab"),
  closure_file = ems_example("GTAP_RE.cls"),
  CPHI = CPHI
)

8.4.3 CSV file

A path to a CSV file can be used as an alternative to a data frame. The CSV must follow the same structure: set index columns and a Value column.

# Write coefficient data to CSV
write.csv(SUBPAR, "SUBPAR.csv", row.names = FALSE)

model <- ems_model(
  model_file = ems_example("GTAP_RE.tab"),
  closure_file = ems_example("GTAP_RE.cls"),
  SUBPAR = "SUBPAR.csv"
)

8.4.4 Combining injections

Multiple coefficient injections can be combined in a single call along with variable omissions:

model <- ems_model(
  model_file = ems_example("GTAP_RE.tab"),
  closure_file = ems_example("GTAP_RE.cls"),
  var_omit = c("atall", "avaall", "tfe", "tfm", "tgd", "tgm", "tid", "tim"),
  KAPPA = 0.03,
  SUBPAR = SUBPAR,
  CPHI = CPHI
)

If the coefficient name is not found in the model, an error is raised indicating that the aggregated data coefficient is not declared within the provided model input.

8.4.5 Set naming convention

Set names follow a model-specific concatenation of the standard set name and the variable-specific index (e.g., REGr, COMMc, ACTSa). See the Loading and specifying sets chapter for the full convention table.

8.5 Intertemporal models

For intertemporal models, ems_model() determines temporal dynamics by detecting the timestep header in the Tablo file. By default, the expected header in the GTAP-RE model is "YEAR". If a model uses a different header for timestep data, set it via ems_option_set():

ems_option_set(timestep_header = "AYRS")

If the expected timestep header is not found in the model, an error will be raised with a suggestion to use ems_option_set() to configure a custom timestep header. The same concept applies to the number of timesteps:

ems_option_set(n_timestep_header = "NINTERVAL")

Default values for these settings (and others) may be obtained using:

ems_option_get()

8.6 Future expansions

Write bidirectional Tablo \(\leftrightarrow\) conversion script to allow for model files
auto-omit switch to automatically drop as many variables as possible based on closure and shock specifications
Model file checks are still rudimentary and a more thorough suite of checks will gradually be put in place