GTAPViz: Visualizing GTAP Results from HAR and SL4 Files
Pattawee Puangchit
2025-03-13
Source:vignettes/GTAPViz_vignette.Rmd
GTAPViz_vignette.Rmd
Introduction
This package facilitates the reporting of CGE model outputs,
particularly for GTAP users, but it can also be applied to other results
based on .har
and .sl4
files. Its primary
function is to generate Figures and Tables. Additionally, several
useful tools
are available for data manipulation to enhance figure illustration.
Package Overview
This package streamlines the creation of figures and tables from .HAR and .sl4 results, making academic presentations effortless. Some key features are:
Automated Plot Adjustments – Optimizes plot dimensions, facet settings, and layout dynamically with minimal user input.
Academic-Style Pivot Table – Automatically generates tables alongside figures, making it easy to include both in academic papers.
Intuitive Customization – Modify colors, fonts, legend positions, and other styling elements using simple, adaptable commands.
Full Customization Without Complexity – Built on
ggplot2
, this package simplifies adjustments into intuitive commands likeTRUE/FALSE
, eliminating the need for deep coding.Multiple Export Formats – Save high-resolution figures in PNG and PDF formats simultaneously for presentations, publications, and LaTeX reports.
Comprehensive Documentation – Includes a vignette and built-in help functions covering all customization options—no need to search online.
Before proceeding, ensure that GTAPViz
is installed and
loaded:
if (!requireNamespace("GTAPViz", quietly = TRUE)) {
devtools::install_github("Bodysbobb/GTAPViz")
}
require(GTAPViz)
Note: If the required packages are not yet installed, please refer to:
Figure Types
This package introduces four different plot commands that can generate more than 10 different plots:
comparison_plot
: Compares variables across all experiments for selected observations from a selected dimension (e.g., region, sector). Examples:qgdp
,ppriv
,EV
.detail_plot
: Visualizes a variable across all or selected observations from one or two dimensions for each experiment. Examples:qo
,qxw
,qmw
.macro_plot
: Shows global macroeconomic indicators or data without dimensions, with each experiment as a single aggregated value. Examples:pgdpwld
,qgdpwld
,vgdpwld
.stack_plot
: Displays the composition of a variable for decomposition analysis, such asEV
decomposition from GTAP results.
Report Tables
This package provides a single command for generating several pivot tables designed for academic presentations. This vignette provides some examples in Creating Report Table.
Project Directory
To use this R code, all solution files, including .sl4
and .har
, must be saved from RUNGTAP or CMD and placed
in the same folder.
Adjust the <project.folder>
directory to your
desired path:
project.folder <- "your/folder/path"
# Optional: You might not need to adjust this
input.folder <- paste0(project.folder, "/in")
map.folder <- paste0(project.folder, "/map")
output.folder <- paste0(project.folder, "/out")
By default, this R script assumes that
<project.folder>
contains the following three main
folders:
📂 project.folder/
├── 📂 in/ # Stores all input files
├── 📂 map/ # Stores the mapping file
├── 📂 out/
Input Folder
All input files must be stored in <input.folder>
(default: "/in"
within
<project.folder>
). Each .sl4
and
.har
file must follow the naming conventions outlined in how to name input files to ensure
consistency.
Below is an example of <input.folder>
:
📂 in/
├── 📄 TAR10.sl4
├── 📄 TAR10-WEL.har
├── 📄 SUBT10.sl4
├── 📄 SUBT10-WEL.har
Mapping Folder
The mapping XLSX template is available here: OutputMapping.xlsx. It contains three main sheets:
SL4File and HARFile Sheets
• “Variable” specifies the required variable from each file.
• “Description” is optional for defining variables and plot titles.
• “Unit” is required for all figure commands.
Below is an example of mapping file:
Variable | Description | Unit |
---|---|---|
qgdp | Real GDP Index | percent |
EV | Welfare Equivalents | million USD |
ppriv | Consumer Price Index | percent |
qo | Output | |
qxw |
Note: The Description and Unit columns can be left empty if using GTAP defaults.
Important: The mapping file is crucial for correctly formatting additional variables—non-GTAPv7 variables.
You can import your external mapping file into R using the following method:
sl4map <- readxl::read_xlsx(map.folder, sheet = "SL4File")
harmap <- readxl::read_xlsx(map.folder, sheet = "HARFile")
Or manually create it in the R environment using the following code:
mapping_df <- data.frame(
Variable = c("qgdp", "EV", "ppriv"),
Description = c("Real GDP Index", "Welfare Equivalents", "Consumer Price Index"),
Unit = c("Percent", "million USD", "percent"),
stringsAsFactors = FALSE
)
FilterData Sheet
This sheet is optional and can also be defined in R instead. It contains two columns for filtering data from the dataframe.
• “Region” excludes specified regions by filtering the “REG” column in all dataframes.
• “Sector” excludes specified sectors by filtering the “COMM” and “ACTS” columns in all dataframes.
💡 Tip: These columns also determine the sorting order. See Sorting Output for details.
Below is an example of the filter data sheet:
Region | Sector |
---|---|
EastAsia | |
SEAsia | |
Oceania |
Note: You may leave it empty to include all entries or redefine the order for sorting the output format.
You can import your external mapping file into R using the following method:
filter.map <- readxl::read_xlsx(map.folder, sheet = "FilterData")
selected_regions <- if(length(filter.map$Region) > 0) filter.map$Region else NULL
selected_sector <- if(length(filter.map$Sector) > 0) filter.map$Sector else NULL
Or manually create it in the R environment using the following code:
selected_regions <- c("EastAsia", "SEAsia", "Oceania")
selected_sector <- NULL
💡 Tip: If the plot is too dense or unclear, try filtering more data!
R Environment Configuration
This section configures experiment names, description and unit handling, and output formats for processing GTAP model results.
Experiment Names
Define <experiment>
to specify input file
names. The experiment name:
• Appears in plots and is added to the “Experiment” column. While renaming files within R is possible using rename value, manual renaming the input file name is recommended.
• Sorts figures and tables based on the order of
<experiment>
. See Sorting Output for details.
The following command processes the files and sorts the output with EXP1 before EXP2:
experiment <- c("TAR10", "SUBT10")
# Automatically Processing These Inputs in the Input Folder
# - TAR10.sl4 and TAR10-WEL.har
# - SUBT10.sl4 and SUBT10-WEL.har
Note: You can include as many experiments (inputs) as needed, but a higher number will increase processing time.
Description and Unit
<info.mode>
controls how the
“Description” and “Unit” columns are
included in the output:
-
"Yes"
→ Uses descriptions and units from the mapping file.
-
"No"
→ Excludes"Description"
and"Unit"
.
-
"GTAPv7"
→ Applies default definitions and units from GTAP Model Version 7.
-
"Mix"
→ Uses manual values when available; otherwise, applies GTAP defaults.
info.mode <- "Mix"
Note: GTAP defaults apply only to variables included in the GTAPv7 model. Any additional variables must be manually defined.
Output Formats
Select the required output formats ("Yes"
= export,
"No"
= skip):
-
CSV (
csv.output
) →"No"
-
STATA (
stata.output
) →"No"
-
R (
r.output
) →"Yes"
-
Text (
txt.output
) →"Yes"
You can also choose to export only the organized raw data, with or
without visualization, by setting plot_data
to
TRUE
or FALSE
.
The following command exports all formats and generates data for plotting:
csv.output <- "YES"
stata.output <- "YES"
r.output <- "YES"
txt.output <- "YES"
plot_data = TRUE
R Configuration Summary
In summary, the entire R setup is captured in the following chunk:
# 1. Project Directory
project.folder <- "your/project/folder"
# 2. Define the Input Names
experiment <- c("TAR10", "SUBT10")
# 3. Adding Description / Unit (Yes/No/GTAPv7/Mix)
info.mode <- "Mix"
# 4. Choosing Output: (CSV, STATA, R, TEXT)
csv.output <- "No"
stata.output <- "No"
r.output <- "No"
txt.output <- "No"
# 5. For Plotting: (TRUE/FALSE)
plot_data = TRUE
💡 Tip: Once this process is complete, you can use the same format for future documents—saving you time and ensuring consistency.
You can simply run the following code to setup subdirectories without modification if you followed all the previous instructions:
# Default Subdirectories:
input.folder <- paste0(project.folder, "/in")
map.folder <- paste0(project.folder, "/map")
output.folder <- paste0(project.folder, "/out")
# Default Mapping File:
sl4map <- readxl::read_xlsx(paste0(map.folder, "/OutputMapping.xlsx"), sheet = "SL4File")
harmap <- readxl::read_xlsx(paste0(map.folder, "/OutputMapping.xlsx"), sheet = "HARFile")
filter.map <- readxl::read_xlsx(paste0(map.folder, "/OutputMapping.xlsx"), sheet = "FilterData")
# Filtering Data:
selected_regions <- if(length(filter.map$Region) > 0) filter.map$Region else NULL
selected_sector <- if(length(filter.map$Sector) > 0) filter.map$Sector else NULL
Note: If you’re familiar with R and prefer a more flexible directory structure, you can customize any of these. However, you must also define them in the function.
Sorting Rules
These predefined lists determine the display order of outputs, i.e., figures and tables:
<experiment>
sorts the column"Experiment"
, i.e., your input files.<selected_region>
sorts the column for defined countries by GTAP; the default is"REG"
.<selected_sectors>
sorts the column for defined sectors by GTAP; the default is"COMM"
and"ACTS"
.
💡 Tip: To customize sorting for additional columns, see Sorting Data.
For example, this setup with will display the figure as shown below:
experiment <- c("TAR10", "SUBT10")
selected_regions <- c("EastAsia", "SEAsia", "Oceania")

Automated Data Extraction
To streamline figure generation from GTAP results, I developed an automated data extraction method using the following command:
auto_gtap_data(
experiment = experiment,
process_sl4_vars = sl4map,
process_har_vars = harmap,
mapping_info = info.mode,
sl4_mapping_info = sl4map,
har_mapping_info = harmap,
region_select = selected_regions,
sector_select = selected_sector,
subtotal_level = FALSE,
project_path = project.folder,
plot_data = plot_data,
output_formats = list(
"csv" = csv.output,
"stata" = stata.output,
"rds" = r.output,
"txt" = txt.output))
The default process for extracting data in automation uses
HARplus::group_data_by_dims
for .sl4
and
get_data_by_var
for .har
.
💡 Tip: The process in ?auto_gtap_data
can be modified for both .sl4
and .har
files,
making it more suitable for certain datasets, including non-GTAP
variables.
Keep in mind that the plot functions may require slight modifications to accommodate the new format.
Converting Units and Labels (Optional)
These optional but recommended steps improve figure clarity. Use the following code to convert million USD to billion USD after data extraction:
sl4.plot.data <- convert_units(sl4.plot.data,
scale_auto = "mil2bil")
har.plot.data <- convert_units(har.plot.data,
scale_auto = "mil2bil")
Note: This function supports various unit
conversions, while scale_auto
simplifies common conversions
such as mil2bil, bil2mil, pct2frac, and frac2pct. You can define custom
conversions manually—see Converting
Units or ?convert_units
for details.
Visualization: Essential Information
Understanding Function Arguments
Before generating any figures, it is useful to review the function arguments to ensure you take full advantage of the available customization options:
?comparison_plot
?detail_plot
?stack_plot
Customizing the Plot Styles
This package builds on ggplot2, making nearly all of its customization options easily adjustable within its plotting functions.
Elements like font sizes, titles, value labels, and positioning can be
modified using simple numeric or logical values
(TRUE/FALSE
).
To view all customization options run:
?get_plot_style_config
plot_config <- get_plot_style_config("default", as_dataframe = TRUE)
Customizing the Figure Outputs
This package allows exporting figures in PNG and PDF formats. PDF files can be merged into a single file or saved as multiple separate files. To see all available options, see:
export_config <- get_export_config(as_dataframe = TRUE)
Highly Recommended for Advanced Configurations
To simplify modifications and maintain structured code, a printing function is provided. This function displays available options, allowing you to adjust and apply a custom plot style across all plot functions.
Firstly, multiple color_tone
options are available in this
package.
You can view all predefined palettes by using the following code:
# Get all palettes as a list
all_palettes <- get_color_palette("all")
# Click or call a specific palette to view its colors
all_palettes$winter("qualitative") # View the winter palette
all_palettes$fall("sequential") # View the fall palette
all_palettes$gtap("diverging") # View the GTAP palette
Note: You can also define any other color palette
simply by using "blue"
, "red"
, or any other
standard color name that works with ggplot2
.
Next, use the following code to create and apply your own plot style:
get_all_config(printing = TRUE)
Please refer to another vignetter Plot Configurations for more details and how to use it
Creating Figures
Comparison Plot
This figure compares one or multiple variables across all experiments for selected observations from a chosen dimension (e.g., region, sector).
Key Features
Designed for comparing selected variables across experiments.
Displays all selected variables in one plot, making it ideal for a few observations; too many can make it dense and unclear.
For example, plotting qgdp
, ppriv
,
EV
, tot
, and u
generates six
separate figures using the following command:
reg_data = sl4.plot.data[["1D"]][["Region"]]
comparison_plot(data = reg_data,
x_axis_from = "Region",
split_by = "Variable",
panel_var = "Experiment",
variable_col = "Variable",
filter_var = NULL,
unit_col = "Unit",
desc_col = "Description",
var_name_by_description = TRUE,
add_var_info = TRUE,
invert_pane = FALSE,
separate_figure = FALSE,
export_picture = TRUE,
export_as_pdf = "merged",
output_path = output.folder,
# See ?export_config
export_config = list(
width = 20,
height = 12
),
# See ?plot_style_config
plot_style_config = list(
color_tone = "purdue",
color_palette_type = "qualitative",
add_unit_to_title = TRUE,
title_format = list(
type = "prefix",
text = "Impact on"
),
panel_rows = 2
))
By default, you might not need to define as much, as the previous sample code assumes that you follow all the previous instructions. You may use the following command to get the exact same output:
comparison_plot(reg_data,
x_axis_from = "Region",
split_by = "Variable",
var_name_by_description = TRUE,
export_picture = TRUE,
output_path = output.folder,
plot_style_config = list(
color_tone = "purdue",
title_format = list(
type = "prefix",
text = "Impact on"
),
panel_rows = 2
))
GTAP Macro Variable Plot
This figure displays aggregated values across all experiments,
typically for global economic impacts. It is designed for GTAP Macro
variables extracted from the “Macros” header in
<.sl4>
files.
Key Features
Compares macroeconomic indicators across experiments.
Works with aggregated data, making it ideal for global-scale analysis.
Primarily used for GTAP Macro variables but can be applied to other aggregated datasets.
💡 Tip: If you have not imported the GTAP Macro data, please see GTAP Macro Data Extraction.
To plot this figure—the only difference from previous figures is
changing split_by = FALSE
—you can use the following
command:
comparison_plot(GTAPMacro,
x_axis_from = "Variable",
split_by = FALSE,
filter_var = c("pgdpwld", "qgdpwld", "vgdpwld"),
export_picture = TRUE,
export_as_pdf = "merged",
export_config = list(
width = 20,
height = 15
),
output_path = output.folder,
plot_style_config = list(
color_tone = "blue",
title_format = list(
type = "full",
text = "Global Economic Impacts"
)
))
(splt_by = FALSE, panel_rows and panel_cols = NULL i.e., default)
Detail Plot
This figure visualizes large-scale data, displaying all sectors (COMM, ACTS) or all regions (REG) within each experiment.
Key Features
Supports visualization across two selected dimensions.
Suitable for datasets too large for comparison_plot.
Automatically detects and aligns variables with different dimension names.
Filters data by selecting the most affected variables using top_impact.
For example, the following command plots all variables with sectors on the x-axis for each region:
detail_plot(sl4.plot.data[["2D"]],
x_axis_from = "Sector",
split_by = "Region",
top_impact = NULL,
var_name_by_description = TRUE,
invert_pane = TRUE,
separate_figure = FALSE,
export_config = list(
width = 45,
height = 20
),
export_picture = TRUE,
export_as_pdf = FALSE,
output_path = output.folder,
plot_style_config = list(
positive_color = "#2E8B57",
negative_color = "#CD5C5C",
panel_rows = 1,
panel_cols = NULL,
show_axis_titles_on_all_facets = FALSE,
y_axis_text_size = 25,
bar_width = 0.6,
all_font_size = 1.1
))
💡 Tip: You may notice the following adjustments: -
positive_color
and negative_color
: Define
colors for positive and negative values, automatically distinguishing
impacts by shade.
show_axis_titles_on_all_facets
: Suppresses repeated labels across facets.y_axis_text_size
: Increases y-axis label size to 25 from the default setting.bar_width
: Decreases bar width for better visualization of large datasets.all_font_size
: Increases all font sizes to 1.3 from the default setting.
(top_impact = NULL, invert_pane = TRUE, panel_rows = 1)
(top_impact = 10, invert_pane = TRUE)
Decomposition (Stack) Plot
This plot visualizes decomposition results, showing how different components contribute to a total value, making it particularly suitable for decomposition analysis.
Key Features
Displays the contribution of components to a total value.
Allows further decomposition by unstacking components instead of using a stacked bar.
Suitable for welfare decomposition, trade decomposition, and other GTAP structural breakdowns.
💡 Tip: Since decomposition data often contains multiple components, renaming and restructuring may be necessary before plotting. You can try the following code:
# Rename Value if needed
wefare.decomp.rename <- data.frame(
ColumnName = "COLUMN",
OldName = c("alloc_A1", "ENDWB1", "tech_C1", "pop_D1", "pref_G1", "tot_E1", "IS_F1"),
NewName = c("Alloc Eff.", "Endwb", "Tech Chg.", "Pop", "Perf", "ToT", "I-S"),
stringsAsFactors = FALSE
)
har.plot.data <- rename_value(har.plot.data, mapping.file = wefare.decomp.rename)
# Rename Column
rename_col <- data.frame(
old = c("REG", "COMM", "ACTS"),
new = c("Region", "Commodity", "Activity")
)
har.plot.data <- HARplus::rename_dims(har.plot.data, rename_col)
Then, you can use the following command to plot the decomposition figure:
stack_plot(data = har.plot.data[["A"]],
x_axis_from = "Region",
stack_value_from = "COLUMN",
split_by = FALSE,
show_total = TRUE,
unstack_plot = FALSE,
var_name_by_description = TRUE,
invert_pane = FALSE,
separate_figure = FALSE,
export_picture = TRUE,
export_as_pdf = "merged",
export_config = list(
width = 28,
height = 15
),
output_path = output.folder,
plot_style_config = list(
color_tone = "gtap",
panel_rows = 2,
panel_cols = NULL,
show_legend = TRUE,
show_axis_titles_on_all_facets = FALSE
))
(split_by = FALSE, show_total = TRUE, unstack_plot = TRUE)
(split_by = FALSE, show_total = TRUE, unstack_plot = FALSE)
Another practical example is plotting the decomposition of terms of trade (header E1), which is also a good example of multi-dimensional plotting. You may try the following command:
stack_plot(data = har.plot.data[["E1"]],
x_axis_from = "Commodity",
stack_value_from = "PRICES",
split_by = "Region",
show_total = TRUE,
unstack_plot = FALSE,
var_name_by_description = TRUE,
invert_pane = TRUE,
separate_figure = FALSE,
export_picture = TRUE,
export_as_pdf = FALSE,
export_config = list(
width = 50,
height = 30
),
output_path = output.folder,
plot_style_config = list(
title_format = list(
type = "prefix",
text = "Terms of Trade Decomposition",
sep = ": "
),
color_tone = "blue",
panel_rows = 1,
show_axis_titles_on_all_facets = FALSE,
bar_width = 0.5,
bar_spacing = 0,
title_size = 48,
x_axis_title_size = 32,
y_axis_title_size = 32,
x_axis_text_size = 20,
y_axis_text_size = 20,
show_legend = TRUE
))
(split_by = “Region”, plot_style_config -> adjustments)
Report Table: Essential Information
Understanding Function Arguments
Before generating any tables, it is useful to review the function arguments to ensure you take full advantage of the available customization options:
?report_table
A limitation of this reporting table function is that the input data must be in a list format. The following code provides an example of how to convert data into this format:
data_list = list(DataFrame = DataFrame)
Key Parameters
In this vignette, I will clarify some of the more complex parameters
of the reporting table function. However, additional arguments are
available, which you can explore by running
?report_table
.
For example, using the following code settings:
report_table(
data_list = data_list,
pivot_col = list(Region = "Variable"),
group_by = list(
Region = list("Experiment", "Region")),
rename_cols = list("Experiment" = "Scenario"),
total_column = FALSE)
data_list
: A named list of data list to process.-
pivot_col
: Defines a pivot column for each dataset, converting it into a wide format. Only one pivot column can be defined per dataset.- Dataset A pivots by
COLUMN
.
- Dataset E1 pivots by
PRICES
.
- Dataset A pivots by
-
group_by
: Defines hierarchical grouping for each dataset, where column order determines the hierarchy.- A groups first by
Experiment
, then byREG
.
- E1 adds
COMM
as a third grouping level.
- A groups first by
-
rename_cols
: Specifies column renaming across all datasets.- Any dataset containing
REG
will rename it toRegion
.
-
COMM
andExperiment
will be renamed toCommodities
andScenario
.
- Any dataset containing
Creating Report Table
This command generates multiple table formats suitable for academic presentations with minimal adjustments. You can process multiple data frames in the same session, even with different pivot formats, but each must be defined separately. See the sample code for details.
Note:
If you want to change values in a column, such as region names, do so
before creating the report table (see Renaming Values in a Dataframe).
Comparison Table
report_table(
data_list = sl4.plot.data[["1D"]],
pivot_col = list(Region = "Variable"),
group_by = list(
Region = list("Experiment", "Region")),
rename_cols = list("Experiment" = "Scenario"),
total_column = FALSE,
decimal = 4,
subtotal_level = FALSE,
repeat_label = FALSE,
include_units = TRUE,
var_name_by_description = TRUE,
add_var_info = TRUE,
add_group_line = FALSE,
separate_sheet_by = "Unit",
export_table = TRUE,
output_path = output.folder,
separate_file = FALSE,
workbook_name = "Comparison Table"
)
(separate_sheet_by = “Unit”)
GTAP Macro Table
GTAPMacro <- list(GTAPMacro = GTAPMacro)
report_table(
data_list = GTAPMacro,
pivot_col = list(
GTAPMacro = "Experiment"),
group_by = list(
GTAPMacro = list("Variable")),
rename_cols = list("Experiment" = "Scenario"),
total_column = FALSE,
decimal = 4,
subtotal_level = FALSE,
repeat_label = FALSE,
include_units = TRUE,
var_name_by_description = FALSE,
add_var_info = FALSE,
add_group_line = FALSE,
separate_sheet_by = NULL,
export_table = TRUE,
output_path = output.folder,
separate_file = FALSE,
workbook_name = "GTAPMacro Table"
)
(separate_sheet_by = FALSE)
Detail Table
report_table(
data_list = sl4.plot.data[["2D"]],
pivot_col = list(Sector = "Sector"),
group_by = list(
Sector = list("Experiment", "Variable", "Region")),
rename_cols = list("Experiment" = "Scenario"),
total_column = FALSE,
decimal = 2,
subtotal_level = FALSE,
repeat_label = FALSE,
include_units = TRUE,
var_name_by_description = TRUE,
add_var_info = TRUE,
add_group_line = TRUE,
separate_sheet_by = NULL,
export_table = TRUE,
output_path = output.folder,
separate_file = FALSE,
workbook_name = "Detail Table"
)
(separate_sheet_by = NULL, add_group_line = TRUE)
Decomposition Table
report_table(
data_list = har.plot.data,
pivot_col = list(A = "COLUMN",
E1 = "PRICES"),
group_by = list(
A = list("Experiment", "REG"),
E1 = list("Experiment", "REG", "COMM")
),
rename_cols = list("REG" = "Region",
"COMM" = "Commodities",
"Experiment" = "Scenario"),
total_column = TRUE,
decimal = 6,
subtotal_level = FALSE,
repeat_label = FALSE,
include_units = TRUE,
var_name_by_description = FALSE,
add_var_info = FALSE,
add_group_line = FALSE,
separate_sheet_by = "REG",
export_table = TRUE,
output_path = output.folder,
separate_file = FALSE,
workbook_name = "Decomposition Table"
)
(total_column = TRUE, separate_sheet_by = “Region”)
Additional Utilities
Adding Unit and Description Columns
If you manually import data or need to adjust the
"Description"
and "Unit"
columns, you can use
the following command:
mapping_df <- data.frame(
Variable = c("qgdp", "EV", "ppriv"),
Description = c("Real GDP Index", "Welfare Equivalents", "Consumer Price Index"),
Unit = c("Percent", "million USD", "percent"),
stringsAsFactors = FALSE
)
datasets <- add_mapping_info(mapping_df, external_map = mapping_df, mapping = "Yes")
Note: Use ?add_mapping_info
to
understand the meaning of mapping
.
Converting Units and Values
GTAP default values are typically reported in million USD, which may be too large for aesthetic plotting. This command converts units across all variables and data frames.
You can convert all units in a dataframe at once, but the order must be defined correctly:
-
change_unit_from
: The original unit name in the"Unit"
column to be changed.
-
change_unit_to
: The new unit name to be recorded in the"Unit"
column.
-
adjustment
: The mathematical operation (/
,*
,+
, or-
) to transform the value.
Example Conversions
• Convert million USD
to billion USD
by
dividing by 1,000.
• Convert percent
to proportion
by dividing by
100.
datasets <- convert_units(change_unit_from = c("million USD", "percent"),
change_unit_to = c("billion USD", "proportion"),
adjustment = c("/1000", "/100"))
Renaming Columns and Data List Names
To modify column names across all datasets and/or rename data list
names automatically—such as changing REG
to
Region
or COMM
to Commodity
—use
the following command:
# Creating Mapping File
rename_col <- data.frame(
old = c("REG", "COMM", "ACTS"),
new = c("Region", "Commodity", "Activity")
)
har.plot.data <- HARplus::rename_dims(har.plot.data, rename_col)
💡 Tip: You can create this mapping dataframe in Excel and import it into R. The column names must be “old” and “new”.
Renaming Values in a Dataframe
To automatically modify values in any column before plotting—such as
renaming country names in the REG
column (e.g., changing
"USA"
to "United States"
or "CHN"
to "China"
)—use the following command:
# Creating Mapping File
rename.region <- data.frame(
ColumnName = "REG",
OldName = c("USA", "CHN"),
NewName = c("United States", "China"),
stringsAsFactors = FALSE
)
har.plot.data.rename <- rename_value(har.plot.data, mapping.file = rename.region)
💡 Tip: You can create this mapping dataframe in
Excel and import it into R. The column names must be
“OldName” and “NewName”, while
column_name
can be defined directly in the command. See
<?rename_value>
for details.
Sorting Data
This function sorts data columns before generating plots or tables. Key arguments:
cols
specifies the column(s) to sort based on a predefined order (e.g., insl4.plot.data
,Experiment
andRegion
will follow the defined order).sort_by_value_desc
controls whether sorting is in descending order (TRUE/FALSE/NULL
). See?sorting_specs
for details.
To apply sorting, use the following command:
# Creating Sorting File
sorting_specs <- data.frame(
Experiment = c("US_All10_RetalTar", "US_All", "US_All10", "US_Specific"),
Region = c("CHN", "USA", "ROW", "CAN")
)
regional_data <- sort_plot_data(
sl4.plot.data,
sort_columns = sorting_specs,
sort_by_value_desc = NULL
)
Note: This function performs sorting, not filtering. Unlisted values remain in the dataset, following the prioritized order.
Hybrid Data Processing: Automation & Manual Adjustments
This process modifies auto_gtap_data
to extract data
using different methods from HARplus
, while allowing
adjustments to priority_list
for
"HARplus::group_data_by_dims"
(see
?auto_gtap_data
).
It is particularly useful when working with additional variables
beyond the GTAP default model, such as defining a new dimension,
"AREG"
, which represents a group of regions. By default,
automation does not recognize "AREG"
as
"Region"
, potentially leading to incorrect grouping in the
data list.
To facilitate data extraction for plotting and reporting table creation, consider the following approach:
auto_gtap_data(
# Input Main File Names
experiment = experiment,
# Input File Suffixes
sl4_suffix = "",
har_suffix = "-WEL",
# Directories
input_path = input.folder,
output_path = output.folder,
# Variable Selection
process_sl4_vars = sl4map,
process_har_vars = harmap,
# Description and Unit Mapping (if `mapping_info` is set to "Yes" or "Mix")
sl4_mapping_info = sl4map,
har_mapping_info = harmap,
mapping_info = info.mode,
# Region and Sector Filtering
region_select = selected_regions,
sector_select = selected_sector,
# Data Extraction Process
sl4_extract_method = "get_data_by_dims",
har_extract_method = "get_data_by_var",
subtotal_level = FALSE,
# If using `"group_data_by_dims"`, a `priority_list` is required. See `?HARplus::group_data_by_dims`.
sl4_priority = NULL,
har_priority = NULL,
# Output Formats
plot_data = plot_data,
output_formats = list(
"csv" = csv.output,
"stata" = stata.output,
"rds" = r.output,
"txt" = txt.output
),
# Output Names for Plot Data
sl4_output_name = "sl4.plot.data",
har_output_name = "har.plot.data",
macro_output_name = "GTAPMacro"
)
Manual Data Processing
This section is for non-GTAP models or manual data extraction for plotting. Follow these steps:
Use
"HARplus::load_sl4x"
or"HARplus::load_harx"
, then"HARplus::group_data_by_dims"
to structure the data in the required format.Filter each dataframe using standard R
data.frame
operations.Add the “Unit” and “Description” columns using
"add_mapping_info"
(the “Unit” column is required for plotting).
# Step 1: Extracting Data
sl4data1 <- HARplus::load_sl4x(system.file("extdata", "EXP1.sl4", package = "HARplus"))
sl4data2 <- HARplus::load_sl4x(system.file("extdata", "EXP2.sl4", package = "HARplus"))
sl4data <- HARplus::get_data_by_dims(NULL, sl4data1, sl4data2, merge_data = TRUE)
# Step 2: Filtering Data using Dataframe and lapply
manual.data <- lapply(sl4data, function(x) {
if (is.data.frame(x)) {
x[x$REG %in% selected_regions & x$COMM %in% selected_sector & x$ACTS %in% selected_sector
& x$Experiment %in% selected_exp , ]
} else {
x
}
})
# Step 3: Adding Unit and Description Column
manual.data <- add_mapping_info(manual.data, external_map = "/your/mapping.xlsx",
description_info = TRUE,
unit_info = TRUE)
GTAP Macro Data Extraction
Extract GTAP Macro variables from the “Macros” header in
.sl4
files using the following command:
Macros <- gtap_macros_data(
input_path = input.folder,
experiment = experiment,
subtotal_level = FALSE
)
Sample Data
Sample data used in this vignette is obtained from the GTAPv7 model and utilizes data from the GTAP 11 database. For more details, refer to the GTAP Database Archive.