4  Example files

4.1 Overview

ems_example() writes bundled example model and script files to disk. It is a good starting point for new users, providing ready-to-run material for each of the six vetted models without requiring any additional setup beyond GTAP data access.

Two output modes are available, controlled by the type argument:

  • "model_files" (default): writes the model (.tab) and closure (.cls) files for the chosen model.
  • "scripts": writes a complete set of example R scripts covering a range of shock, swap, and solver configurations supported by that model. Each script is a self-contained, runnable workflow from data loading through to result parsing.
ems_example(
  model,
  path,
  type = c("model_files", "scripts"),
  dat_input = NULL,
  par_input = NULL,
  set_input = NULL
)

4.2 Arguments

Argument Default Description
model Model name. One of "GTAPv6", "GTAPv7", "GTAP-RE", "GTAP-AEZ", "GTAP-E", "GTAP-EP"
path Directory where files will be written
type "model_files" Output type: "model_files" or "scripts"
dat_input NULL Path to the basedata HAR file, or the dat list from GTAP_convert(). Required when type = "scripts"
par_input NULL Path to the parameters HAR file, or the par list from GTAP_convert(). Required when type = "scripts"
set_input NULL Path to the sets HAR file, or the set list from GTAP_convert(). Required when type = "scripts"

4.3 Writing model files

The simplest use of ems_example() extracts a model’s Tablo and closure files so they can be inspected or used directly with ems_model() or solve_in_situ().

library(teems)

# Write GTAPv7 model files to a temporary directory
paths <- ems_example("GTAPv7", tempdir())

# Or to a specific directory
paths <- ems_example("GTAP-RE", "~/my_project/model")

The returned list contains two named paths:

paths[["model_file"]]   # path to the .tab file
paths[["closure_file"]] # path to the .cls file

These can be passed directly to ems_model():

model <- ems_model(
  model_file = paths[["model_file"]],
  closure_file = paths[["closure_file"]]
)

4.4 Writing example scripts

When type = "scripts", ems_example() writes a directory of R scripts covering a range of configurations available for the chosen model. Each script is injected with the supplied data paths and is immediately runnable.

paths <- ems_example(
  model = "GTAPv7",
  path = "~/my_project",
  type = "scripts",
  dat_input = "~/dat/GTAP/v12/flexAgg/gsdfdat.har",
  par_input = "~/dat/GTAP/v12/flexAgg/gsdfpar.har",
  set_input = "~/dat/GTAP/v12/flexAgg/gsdfset.har"
)

The GTAP-AEZ scripts need a GTAP-AEZ database (GTAP 11c or newer). The scripts pass the HAR files to ems_data(), which prepares the AEZ layer on load; GTAP_convert(target = "GTAP-AEZ") gives the prepared, unaggregated database in R (see GTAP-AEZ, GTAP-E and GTAP-Power databases):

paths <- ems_example(
  model = "GTAP-AEZ",
  path = "~/my_project",
  type = "scripts",
  dat_input = "~/dat/GTAP-AEZ/v12a/gsdfdat.har",
  par_input = "~/dat/GTAP-AEZ/v12a/gsdfpar.har",
  set_input = "~/dat/GTAP-AEZ/v12a/gsdfset.har"
)

The GTAP-E scripts need a GTAP-E database (GTAP 12a or newer), prepared by ems_data() on load or with GTAP_convert(target = "GTAP-E") (see GTAP-AEZ, GTAP-E and GTAP-Power databases). They aggregate with the energy mapping, which keeps the energy commodities distinct as the model’s nest requires:

paths <- ems_example(
  model = "GTAP-E",
  path = "~/my_project",
  type = "scripts",
  dat_input = "~/dat/GTAP-E/12a/gsdfdat.har",
  par_input = "~/dat/GTAP-E/12a/gsdfpar.har",
  set_input = "~/dat/GTAP-E/12a/gsdfset.har"
)

The GTAP-EP scripts need a GTAP-Power database (GTAP 12a or newer), prepared by ems_data() on load or with GTAP_convert(target = "GTAP-EP") (see GTAP-AEZ, GTAP-E and GTAP-Power databases). They aggregate with the power mapping, which keeps transmission, base load and peak load apart as the generation nest requires:

paths <- ems_example(
  model = "GTAP-EP",
  path = "~/my_project",
  type = "scripts",
  dat_input = "~/dat/GTAP-P/12a/gsdfdat.har",
  par_input = "~/dat/GTAP-P/12a/gsdfpar.har",
  set_input = "~/dat/GTAP-P/12a/gsdfset.har"
)

The data inputs can also be the in-memory list objects returned by GTAP_convert(), which is useful when the raw data needs format conversion before running:

# Convert v7 data to v6.2 format, then generate scripts for the classic model
converted <- GTAP_convert(
  dat_har = "~/dat/GTAP/v12/gsdfdat.har",
  par_har = "~/dat/GTAP/v12/gsdfpar.har",
  set_har = "~/dat/GTAP/v12/gsdfset.har",
  target = "GTAPv6"
)

paths <- ems_example(
  model = "GTAPv6",
  path = "~/my_project",
  type = "scripts",
  dat_input = converted$dat,
  par_input = converted$par,
  set_input = converted$set
)

When list objects are supplied, ems_example() writes data to RDS files alongside the scripts and injects readRDS() calls at the top of each script in place of plain path assignments.

4.5 Using the generated scripts

ems_example() returns a character vector of paths, one per written script. Each script is ready to run; the data paths supplied to ems_example() are injected at the top of the file as plain assignments.

4.5.1 Script naming convention

Script file names encode the shock and swap configuration (the exact set varies by model):

File name What it demonstrates
null.R Zero-shock run — useful for verifying the model solves before applying shocks
numeraire.R Uniform shock to the numeraire (pfactwld): all prices move by the shock and real variables stay unchanged
full_uniform.R Uniform shock across all elements of a variable
part_uniform.R Uniform shock on a subset of elements
part_uniform_full_swap.R Partial shock plus a full-variable closure swap
part_uniform_part_swap.R Partial shock plus a partial closure swap
part_uniform_part_swap_mixed.R Partial shock plus mixed (full + partial) swaps
part_uniform_subset_swap.R Partial shock and swaps with mixed multiple elements and subsets
custom_full.R Heterogeneous shock values supplied as a data frame
custom_partial.R Heterogeneous shock values supplied as a data frame on a subset of elements
custom_full_csv.R Heterogeneous shock values read from a CSV file
custom_partial_*.R Heterogeneous shocks with one or more dimensions fixed to elements
*_year.R, scenario.R Intertemporal models only: shocks by chronological year, and a scenario shock

4.5.2 Structure of a generated script

Each script begins with the injected assignments followed by the template body. Opening part_uniform.R in an editor shows:

dat_input = "~/dat/GTAP/v12/flexAgg/gsdfdat.har"
par_input = "~/dat/GTAP/v12/flexAgg/gsdfpar.har"
set_input = "~/dat/GTAP/v12/flexAgg/gsdfset.har"
model_file = "~/my_project/GTAP-RE.tab"
closure_file = "~/my_project/GTAP-RE.cls"

dat <- ems_data(
  dat_input = dat_input,
  par_input = par_input,
  set_input = set_input,
  time_steps = c(0, 1, 2),
  REG = "big3",
  ACTS = "macro_sector",
  ENDW = "labor_agg"
)

model <- ems_model(
  model_file = model_file,
  closure_file = closure_file
)

partial <- ems_uniform_shock(
  var = "aoall",
  value = -1,
  REGr = "chn",
  ACTSa = "crops"
)

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  shock = partial
)

outputs <- ems_solve(
  cmf_path = cmf_path,
  matrix_method = "SBBD",
  n_tasks = 2L,
  solution_method = "Gragg"
)

4.6 Output

ems_example() returns a character vector of file paths to the written files. For type = "model_files" this is the .tab and .cls paths. For type = "scripts" this is one path per written script.