8 Closure swaps

8.1 Overview

Swaps allow the user to reconfigure which variables are exogenous (provided by the modeler) and which are endogenous (solved by the model). Simple full variable swaps can be directly inputted as a string into the swap_in and swap_out arguments of ems_deploy(). More complex swaps must be handled with the dedicated ems_swap() function.

8.2 Simple (full variable) swaps

Here, simple swaps refer to swaps in which a variable and all its components are being swapped. This is the most common type of swap and is directly handled within ems_deploy().

A single full variable swap:

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  swap_in = "qfd",
  swap_out = "tfd"
)

Multiple full variable swaps:

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  swap_in = c("qfd", "yp"),
  swap_out = c("tfd", "dppriv")
)

Note that swaps (and validity checks) are handled in the order they are inputted, and swaps “in” are handled before swaps “out”.

8.3 Complex (partial variable) swaps

8.3.1 ems_swap()

ems_swap() prepares a partial variable swap for use in the swap_in or swap_out arguments of ems_deploy(). Set arguments in ... use the model-specific set-index naming convention (set name concatenated with the variable’s index letter, e.g. REGr, ACTSa) to identify which tuples to include in the swap.

ems_swap(var, ...)

Argument	Type	Description
`var`	Character	Variable name as it appears in the model file
`...`	Named arguments	Set-index pairs restricting the swap. Each value is a single element (`"element"`), multiple elements (`c("a", "b")`), or a named subset (`"SUBSET"`)

Partial variable swaps entail swapping parts of a variable (i.e., subsets of the constitutive sets) and must be processed through the ems_swap() function. In the above example the full “qfd” and “yp” variables were made exogenous, while the full “tfd” and “dppriv” variables become endogenous. Within the GTAPv7 model, “qfd” encompasses the “COMM”, “ACTS”, and “REG” sets:

Variable (orig_level=VDFB)(all,c,COMM)(all,a,ACTS)(all,r,REG)
    qfd(c,a,r) # demand for domestic commodity c by activity a in region r #;

What if we wish to shock only certain parts of this variable (e.g., a region or commodity) and allow the remainder of the variable to endogenously adjust according to model equations? In this case we would swap on the parts of the variable that we will provide values to and leave the remainder. If, for example, we have a shock value for “asia” within “REG” and “crops” within “ACTS”, the following ems_swap() call will prepare this swap for input into the swap_in argument of ems_deploy():

qfd_in <- ems_swap(
  var = "qfd",
  REGr = "asia",
  ACTSa = "crops"
)

Note that sets specified in this manner are identified by the model-specific concatenation of the standard set name plus the variable-specific index. This is necessary because many variables contain multiple instances of the same set and none of the teems functions relies upon input entry order or order within the model to make distinctions. In this case the “qfd” set subindices are “c”, “a”, and “r”, yielding “COMMc”, “ACTSa”, and “REGr”. In order to retain a valid closure we also use the same approach to the outgoing variable “tfd”:

tfd_out <- ems_swap(
  var = "tfd",
  REGr = "asia",
  ACTSa = "crops"
)

While the subindices for both variables are the same within GTAPv7, note that these may vary in some models such as GTAPv6 where the REG subindex is “s” for “qfd” and “r” for “tfd”. Both swaps may now be loaded within ems_deploy():

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  swap_in = qfd_in,
  swap_out = tfd_out
)

Or if additional full variable swaps are also desired, a list is used to load multiple swaps for each direction:

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  swap_in = list(qfd_in, "yp"),
  swap_out = list(tfd_out, "dppriv")
)

Finally, selection of multiple elements for each set will expand the swap to encompass all associated tuples. For example:

qfd_in <- ems_swap(
  var = "qfd",
  REGr = c("asia", "lam"),
  ACTSa = "crops"
)

is equivalent to loading

qfd_in_1 <- ems_swap(
  var = "qfd",
  REGr = "asia",
  ACTSa = "crops"
)

and

qfd_in_2 <- ems_swap(
  var = "qfd",
  REGr = "lam",
  ACTSa = "crops"
)

8.3.2 Subset swaps

A named model subset may be passed in place of individual elements. teems expands the subset to all its elements at the aggregation level specified in ems_data(). This is useful when a model defines meaningful groupings that map directly to closure logic — such as margin commodities or forward time steps in intertemporal models.

In the GTAP-RE model, MARG is a subset of COMM containing margin commodities, and FWDTIME is a subset of ALLTIME containing forward time steps. Passing these subset names directly restricts the swap to only those elements:

qxs_in <- ems_swap(
  var = "qxs",
  COMMc = "MARG",
  REGs = c("chn", "usa"),
  ALLTIMEt = "FWDTIME"
)

txs_out <- ems_swap(
  var = "txs",
  COMMc = "MARG",
  REGs = c("chn", "usa"),
  ALLTIMEt = "FWDTIME"
)

cmf_path <- ems_deploy(
  .data = dat,
  model = model,
  shock = partial,
  swap_in = qxs_in,
  swap_out = txs_out
)

Note that REGs = c("chn", "usa") is a multi-element specification, while COMMc = "MARG" and ALLTIMEt = "FWDTIME" are subset specifications — both forms can be combined freely in a single ems_swap() call.