14  Composing results

14.1 Overview

ems_compose() retrieves and processes results from a solved model run. Results are parsed and filtered according to the which argument. Data validation and consistency checks are performed during the parsing process.

By default, ems_solve() calls ems_compose() automatically, so this function is primarily used when suppress_outputs = TRUE was passed to ems_solve() or solve_in_situ(), or when re-parsing results from a previous run.

ems_compose(
  cmf_path,
  which = "all",
  passes = FALSE
)

14.2 Arguments

Argument Default Description
cmf_path Path to the CMF file generated by ems_deploy()
which "all" "all" returns every model variable and coefficient (coefficients at their updated, post-simulation values), except the condensation coefficients (CSUB<n>, see Condensation coefficients), which come back only when named. Otherwise, a character vector of variable and coefficient names to retrieve, matched without regard to case
passes FALSE TRUE adds the separate solutions of a three-pass "Gragg", "Midpoint" or "Euler" run and their accuracy (see Separate solutions)

14.3 Basic usage

After a standard model run with suppressed outputs:

ems_solve(
  cmf_path = cmf_path,
  solution_method = "Gragg",
  matrix_method = "LU",
  suppress_outputs = TRUE
)

# Parse all results
outputs <- ems_compose(cmf_path = cmf_path)

14.4 Filtering output

Pass a character vector of names to which to retrieve a subset of results. Variables and coefficients can be mixed freely in a single call:

# All model variables and coefficients (default)
all_outputs <- ems_compose(cmf_path = cmf_path)

# Single variable by name
qfd <- ems_compose(cmf_path = cmf_path, which = "qfd")

# Single coefficient by name
SAVE <- ems_compose(cmf_path = cmf_path, which = "SAVE")

# Multiple names with mixed variables and coefficients
results <- ems_compose(cmf_path = cmf_path, which = c("qfd", "qfm", "SAVE"))

Note that some coefficient names differ from their associated HAR headers. For example, the coefficient exposed as "VTMFSD" corresponds to the VTWR header. Use the name as it appears in the model file, not the header.

14.5 Return value

ems_compose() returns a tibble with one row per result and four columns:

Column Description
name Variable or coefficient name as it appears in the model file
label Description string from the model file
type "variable", "coefficient" or "postsim" (coefficients computed in a PostSim section)
dat List-column of data.tables, one per row, containing the result values

14.6 Levels results

A variable declared with ORIG_LEVEL= in the model file has a known pre-simulation level: either a coefficient over exactly the variable’s sets (GTAP’s qfd takes VDFB, its value at base prices) or a number (1.0 for a price index). Levels variables know theirs too. For these variables the data.table gains:

Column Percent-change variable Change variable
pre_level pre-simulation level pre-simulation level
post_level pre_level * (1 + Value / 100) pre_level + Value
change / percent_change change: the ordinary change percent_change: the percent change

For runs solved with "BoSha32" or "DoPri54" (see solving), each variable’s data.table also has an error_estimate column. Sort it in descending order to find the least settled results; it is an indicator, not a bound on the error.

14.7 Separate solutions

A three-pass "Gragg", "Midpoint" or "Euler" run extrapolates from three solutions with increasing step counts (see solving). passes = TRUE returns them, so the accuracy of each result can be inspected:

outputs <- ems_compose(cmf_path, passes = TRUE)
attr(outputs, "accuracy")

Each variable’s data.table gains:

Column Description
pass1, pass2, pass3 The solutions with the fewest to the most steps, in the units of Value
figures Significant figures to which the two two-pass extrapolations agree (0 to 6; NA for a result judged zero, both extrapolations below 1e-6)
levels_figures The same for the variable’s levels value, which a percent-change result usually has more of
error The difference between the two extrapolations, in the units of Value
code The convergence code of GEMPACK manual 26.2.3, for example "CX" (confidence in the extrapolated result) or "MD!" (monotonic but appearing to diverge)
summarized Whether the element counts in the run’s accuracy summary: TRUE for endogenous and backsolved results (of the accuracy_vars variables when those are given), FALSE for exogenous elements, whose values the shock sets

The accuracy attribute has one row per variable: elements, summarized, the lowest figures (min_figures, min_levels_figures; a result judged zero counts as 6), the share of results at accuracy_figures or more (share_figures, share_levels_figures; see options), worst_code and max_error. With subintervals, figures and levels_figures are the lowest over the subintervals and code the worst; the pass columns and error come from the last subinterval alone, each pass compounded onto the extrapolated result of the subintervals before it. A run that wrote no separate solutions stops with an error.