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 fileThese 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.