The {teems} R package user manual

Author

Matthew Cantele

1 Introduction

Reproducibility within computable general equilibrium (CGE) and partial equilibrium modeling analyses has long been elusive, in part due to proprietary data and software. Here we address one aspect of this equation with the introduction of the TEEMS (Trade and Environment Equilibrium Modeling System) open-source software suite.

At its core, TEEMS comprises an R package teems used to compose model runs and teems-solver, a C-based solver capable of solving a large system of nonlinear equations by leveraging a range of mathematical and scientific computation libraries. Auxiliary repositories to facilitate model runs include teems-models, containing internally available and immediately compatible models, and teems-mappings, which contains ready-to-use mappings from coarse to fine resolutions for all core sets in most GTAP-based models.

With a base within the general purpose R scripting language, users are able to seamlessly adjust model components including set aggregations, parameter weighting, closure and shock specifications as well as a large number of options pertaining to the solution and model outputs. Model scripts can then be shared with colleagues, reviewers, and policy-makers for vetting, modification, and reproduction.

1.1 Motivation

Reproducibility has been elusive also due to the sheer complexity of compiling a single model run. A “simple” model run, for example, broadly involves:

  1. Data and set selection
  2. Set mappings
  3. Model selection
  4. Variable omission
  5. Closure selection including any swaps
  6. Shock designation
  7. Set-specific basedata loading, modification, and aggregation
  8. Set- and weight-specific parameter loading, modification, and aggregation
  9. Selection of matrix solution methods
  10. Number of step and subinterval designations
  11. Constrained optimization solution
  12. Composition of all outputs into structured data

Due to the complexity involved, in the course of building the TEEMS framework we found that in the absence of a reproducible architecture, there is a very high possibility of persistent logic errors propagating through to the output without any obvious indications that this is taking place.

Models which incorporate time steps and additional auxiliary data (e.g., land-use data) or are coupled with other models as is the case with most integrated assessment models (IAMs) are even more complex and thus more susceptible to a wide range of errors.

Ultimately we hope that this software mitigates the steep learning curve requisite to running equilibrium models and allows scientists from various disciplines to advance model representation of their fields. The TL;DR – running a CGE model does not have to be so hard!

1.2 Errors and model compatibility

This software suite has been under development for many years. Despite our best efforts, it is possible that you will encounter issues – particularly given the wide range of Tablo model files that exist in the field. If your model file does not work, please get in touch and we will seek to expand compatibility.

1.3 About this manual

This manual is a step-by-step user guide to teems.