6 Auxiliary data

6.1 Overview

ems_aux() prepares a single auxiliary input for injection into the ems_data() pipeline via the aux_input argument. Auxiliary data can replace an existing header in the loaded database or introduce a novel header not present in the original files. All auxiliary data is loaded at full (unaggregated) resolution; ems_data() subsequently aggregates it according to the active set mappings and the type argument.

ems_aux(input, type, header = NULL)

Argument	Type	Description
`input`	Data frame, character vector, or file path	The auxiliary data to load. Accepts a data frame or data frame extension (e.g., tibble, data.table) for `"dat"` and `"par"` types; a character vector for `"set"`; or a path to a CSV or GTAP HAR file
`type`	Character	Aggregation type: `"dat"` (sum aggregation), `"par"` (mean or weighted mean aggregation), or `"set"` (final set elements, no aggregation)
`header`	Character or `NULL`	Header name for the input. Required unless `input` is a GTAP HAR file, which already contains header metadata

6.2 Input formats

ems_aux() accepts three input formats determined by input.

6.2.1 Data frame

A data frame, tibble, or data.table containing a Value column and one or more set columns identifying the dimensions of the coefficient. The header argument is required.

# Load at full resolution, modify, then prepare as auxiliary input
.data_full <- ems_data(
  dat_input = "path/to/gsdfdat.har",
  par_input = "path/to/gsdfpar.har",
  set_input = "path/to/gsdfset.har",
  REG = "full", COMM = "full", ACTS = "full", ENDW = "labor_agg"
)

pop <- .data_full$POP
pop$Value <- pop$Value * 1.25

aux_pop <- ems_aux(input = pop, type = "dat", header = "POP")

6.2.2 CSV file

A path to a CSV file formatted identically to the data frame format above (set columns + Value column). The header argument is required.

write.csv(pop, "path/to/pop.csv", row.names = FALSE)
aux_pop <- ems_aux(input = "path/to/pop.csv", type = "dat", header = "POP")

6.2.3 HAR file

A path to a GTAP header array (.har) file. All headers within the file are loaded as a named list. The header argument is not required because the metadata is already contained in the file.

aux_gdp <- ems_aux(input = "path/to/gdpextra.har", type = "par")

6.2.4 Character vector (`type = "set"`)

When type = "set", input can take the form a character vector of set elements. Set inputs define a new named set in the loaded data and are not aggregated; the elements provided become the final set. This is useful when a model references a set that is not derived from the GTAP database (e.g., a tax instrument classification).

tax_types <- c("prodtax", "pfacttax", "inctax", "inputtax",
               "contax", "invtax", "govtax", "xtax", "mtax")

aux_tax <- ems_aux(input = tax_types, type = "set", header = "ALLTAX")

The resulting object is passed to aux_input in ems_data() and will be available in the loaded data under the name ALLTAX.

6.3 Using auxiliary data in `ems_data()`

A single ems_aux() output may be passed directly to aux_input, or multiple outputs combined in a list:

# Single auxiliary input
.data <- ems_data(
  dat_input = "path/to/gsdfdat.har",
  par_input = "path/to/gsdfpar.har",
  set_input = "path/to/gsdfset.har",
  aux_input = aux_pop,
  REG = "big3", COMM = "macro_sector", ACTS = "macro_sector", ENDW = "labor_agg"
)

# Multiple auxiliary inputs
.data <- ems_data(
  dat_input = "path/to/gsdfdat.har",
  par_input = "path/to/gsdfpar.har",
  set_input = "path/to/gsdfset.har",
  aux_input = list(aux_pop, aux_tax, aux_gdp),
  REG = "big3", COMM = "macro_sector", ACTS = "macro_sector", ENDW = "labor_agg"
)

When ems_data() processes auxiliary input, it merges each item into the loaded database before aggregation. The merge behavior differs depending on whether the header already exists in the database.