GTAPViz: Visualizing GTAP Results from HAR and SL4 Files

Pattawee Puangchit

2025-03-13

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 like TRUE/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:

• GTAPViz

• HARplus

Figure Types

This package introduces four different plot commands that can generate more than 10 different plots:

1. comparison_plot: Compares variables across all experiments for selected observations from a selected dimension (e.g., region, sector). Examples: qgdp, ppriv, EV.

2. detail_plot: Visualizes a variable across all or selected observations from one or two dimensions for each experiment. Examples: qo, qxw, qmw.

3. macro_plot: Shows global macroeconomic indicators or data without dimensions, with each experiment as a single aggregated value. Examples: pgdpwld, qgdpwld, vgdpwld.

4. stack_plot: Displays the composition of a variable for decomposition analysis, such as EV 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.

1. Comparison Table

2. GTAP Macro Table

3. Detail Table

4. Decomposition 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/  

Example of Project Folder

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 

Example of Input Folder and Input Files

Mapping Folder

The mapping XLSX template is available here: OutputMapping.xlsx. It contains three main sheets:

• SL4File and HARFile

• FilterData

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

Example of “SL4File” and “HARFile” Sheet

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

Example of “FilterData” Sheet

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")

Example of Sorting Figures

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.

• See Hybrid Data Extraction.

• See Manual Data Processing.

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
                ))

Comparison Plot Visualization

(splt_by = FALSE, panel_rows = 2, panel_cols = NULL i.e., default)

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"
                  )
                ))

GTAP Macro Plot Visualization
(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.

Detail Plot Visualization
(top_impact = NULL, invert_pane = TRUE, panel_rows = 1)

Detail Plot Visualization (filtered)
(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
           ))

Stack Plot Visualization (stack)
(split_by = FALSE, show_total = TRUE, unstack_plot = TRUE)

Stack Plot Visualization (unstacked)
(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
           ))

Stack Plot Visualization (Multi-Dimension)
(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.

• group_by: Defines hierarchical grouping for each dataset, where column order determines the hierarchy.

  • A groups first by Experiment, then by REG.
    
  • E1 adds COMM as a third grouping level.

• rename_cols: Specifies column renaming across all datasets.

  • Any dataset containing REG will rename it to Region.
    
  • COMM and Experiment will be renamed to Commodities and Scenario.

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"
)

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"
)

GTAP Macros 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"
)

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"
)

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., in sl4.plot.data, Experiment and Region 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:

1. Use "HARplus::load_sl4x" or "HARplus::load_harx", then "HARplus::group_data_by_dims" to structure the data in the required format.

2. Filter each dataframe using standard R data.frame operations.

3. 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.