17 Example files

17.1 Overview

ems_example() writes bundled example model and script files to disk. It is the recommended starting point for new users, providing ready-to-run material for each of the four vetted model variants 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 the full 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.

17.2 Arguments

Argument	Default	Description
`model`		Model name. One of `"GTAPv6"`, `"GTAPv7"`, `"GTAP-INT"`, `"GTAP-RE"`
`write_dir`	`tools::R_user_dir("teems", "cache")`	Directory where files are written
`type`	`"model_files"`	Output type: `"model_files"` or `"scripts"`
`dat_input`	`NULL`	Path to the basedata HAR file. Required when `type = "scripts"`
`par_input`	`NULL`	Path to the parameters HAR file. Required when `type = "scripts"`
`set_input`	`NULL`	Path to the sets HAR file. Required when `type = "scripts"`
`target_format`	`NULL`	Target GTAP format for data conversion (e.g. `"GTAPv7"`). Required when `type = "scripts"` and a format conversion is needed

17.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 the default cache directory
paths <- ems_example("GTAPv7")

# Or to a specific directory
paths <- ems_example("GTAP-RE", write_dir = "~/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
)

17.4 Writing example scripts

When type = "scripts", ems_example() writes a directory of R scripts covering the full range of configurations available for the chosen model — uniform shocks, custom shocks, partial shocks, closure swaps, scenario shocks (for intertemporal models), and null runs. Each script is injected with the supplied data paths and is immediately runnable.

paths <- ems_example(
  model      = "GTAPv7",
  write_dir  = "~/my_project",
  type       = "scripts",
  dat_input  = "~/dat/GTAP/v10/flexAgg/gsddat.har",
  par_input  = "~/dat/GTAP/v10/flexAgg/gsdpar.har",
  set_input  = "~/dat/GTAP/v10/flexAgg/gsdset.har"
)

If the HAR files are in a format that requires conversion (e.g. GTAP v9 files being used with a v7.0 model), supply target_format:

paths <- ems_example(
  model         = "GTAPv7",
  write_dir     = "~/my_project",
  type          = "scripts",
  dat_input     = "~/dat/GTAP/v9/flexAgg/gddat.har",
  par_input     = "~/dat/GTAP/v9/flexAgg/gdpar.har",
  set_input     = "~/dat/GTAP/v9/flexAgg/gdset.har",
  target_format = "GTAPv7"
)

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

17.5.1 Script naming convention

Script file names encode the shock and swap configuration:

File name	What it demonstrates
`null.R`	Zero-shock run — useful for verifying the model solves before applying shocks
`numeraire.R`	Uniform 1% population shock — minimal working example
`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_year.R`	Partial shock filtered to a single time step (intertemporal models)
`custom_full.R`	Heterogeneous shock values supplied as a data frame
`custom_full_csv.R`	Heterogeneous shock values read from a CSV file
`custom_full_year.R`	Heterogeneous shock with a time dimension
`scenario.R`	Scenario shock from absolute values (intertemporal models only)

17.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/v10/flexAgg/gsddat.har"
par_input = "~/dat/GTAP/v10/flexAgg/gsdpar.har"
set_input = "~/dat/GTAP/v10/flexAgg/gsdset.har"
target_format = NULL
write_dir = "~/my_project"
model_file = "~/my_project/GTAP-INT.tab"
closure_file = "~/my_project/GTAP-INT.cls"

.data <- ems_data(
  dat_input = dat_input,
  par_input = par_input,
  set_input = set_input,
  REG = "big3",
  TRAD_COMM = "macro_sector",
  ENDW_COMM = "labor_agg",
  time_steps = c(0, 1, 2),
  target_format = target_format
)

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

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

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

outputs <- ems_solve(
  cmf_path = cmf_path,
  matrix_method = "LU",
  solution_method = "Johansen"
)

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

By default, files are written to tools::R_user_dir("teems", "cache") and do not persist across sessions. Specify write_dir to control the output location as well as generate persistent files.