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.