Step 1: Project Setup

This manual provides an explanation of the file 1.ProjectSetup.R

Directories and Input Files

Before proceeding, make sure your project directory is structured as follows:

Replace all sample input files in the /in folder with your own simulation results.
Ensure that OutputMapping.xlsx exists in the /map folder and that you have defined the parameters you want to extract:
- Use the SL4File sheet to select variables from the .sl4 file.
- Use the HARFile sheet to select variables from the .har file.
- The Filter sheet (optional) allows you to:
  - Use the Region column to specify regions (default GTAP column: REG).
  - Use the Sector column to specify sectors (default GTAP columns: COMM and ACTS).

Note: If OutputMapping.xlsx is missing, you can download it again from the OutputMapping.xlsx download page.

📂 project.folder/
├── 📂 in/
│   ├── 📄 IncreaseTar10.sl4
│   ├── 📄 IncreaseTar10-WEL.har
│   ├── 📄 IncreaseTar50.sl4
│   ├── 📄 IncreaseTar50-WEL.har
│   ├── 📄 ...
├── 📂 map/
│   ├── 📄 OutputMapping.xlsx
├── 📂 out/

Example of Project Folder

1 Project Directory

1.1 `project.folder`

R requires forward slashes (/) in the file path.

project.folder <- "c:/your/project/folder"

1.2 `experiment`

List all input file names (.sl4 and/or .har) without suffix, located in the /in folder, in the desired order:

Show explanations for experiment

Note:
(1) Case-sensitive — "Exp1" is different from "exp1"
(2) Display order matters — files listed first will appear first in outputs and figures
(3) Matching names required — simulations must use the same base name for both .sl4 and .har files to align results correctly (e.g., IncreaseTar10.sl4 and IncreaseTar10.har)

experiment <- c("IncreaseTar10", "IncreaseTar50", "ReduceTar20")

1.3 `sl4_suffix / har_suffix`

This is the suffix used in the file name (not the file extension). Use NULL or "" if no suffix is used.

sl4_suffix <- ""
har_suffix <- "-WEL"

1.4 `process_var`

Define which variables to process for sl4 and har separately.

Show explanations for process_var

By default, the setup follows your mapping file sheets “SL4File” and “HARFile”.
- sl4map and harmap: Default mode
- NULL: Select all variables from that file format
- FALSE: Skipping that file format

process_sl4_vars <- "sl4map"  # Leave it like this for default
process_har_vars <- "harmap"  # Leave it like this for default

2 Output Formatting

2.1 `mapping_info`

Show explanations for mapping_info

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

See details in GTAPViz::?add_mapping_info

mapping_info <- "Mix"

2.2 `output formats`

“Yes” or “No”. Available formats: .csv, .dta (Stata), .Rds (R), .txt

csv.output <- "No"    
stata.output <- "No"  
r.output <- "No"
txt.output <- "No"

2.3 `plot_data`

TRUE / FASLE. This will be used for plotting and generating tables in Step 2 and Step 3.

plot_data <- TRUE

2.4 `convert_unit / decimals`

This setting applies unit conversion to all input files matching the specified unit values.

Show explanations for convert_unit / decimals

The default "Unit" is based on your mapping file or "GTAPv7", depending on the mapping_info setting.

"mil2bil": million → billion USD (/1000)
"bil2mil": billion → million USD (*1000)
"pct2frac": percent → fraction (/100)
"frac2pct": fraction → percent (*100)

See details in ?convert_units under scale_auto

sl4_convert_unit <- c("mil2bil")   # Use NULL for no unit conversion
har_convert_unit <- c("mil2bil", "pct2frac")
decimals <- 4

2.5 `rename_columns`

Renames GTAP column identifiers (TRUE or FALSE) to more readable format for all data extraction methods.

Show explanations for rename_columns

REG → Region,
COMM → Commodity,
ACTS → Activity

Note: This setup will only work with those three columns, if you desire to rename additional columns see FAQs - Renaming Columns and Data List Names”

rename_columns <- TRUE

2.6 `subtotal_level`

Set TRUE if subtotals are included in your simulations

subtotal_level <- FALSE

2.7 `add_scenario_ranking`

Options: TRUE, FALSE, or "merged"

Show explanations for add_scenario_ranking

TRUE: Adds a ranking column called "ScenarioRank"
"merged": Also prefixes experiment names in the "Experiment" column with the rank (e.g., (1) ReduceTar50) for display in plots

add_scenario_ranking <- TRUE

Optional - Data Extraction

If you want to manually set up the initial GTAP data or recover after deleting the setup file,
you can copy and paste the following code into your R script to retrieve the required data:

💻 AutoGTAP Codes

Choose Codes:

This function is a default auto_gtap_data applied in default setup of 1.ProjectSetup.R


# Directory Setup and Input Files
project.folder <- "your/project.directory"  # Use forward slashes (/)
experiment <- c("IncreaseTar10", "IncreaseTar50", "ReduceTar20")  # Replace with your case names
sl4_suffix <- ""       # Suffix for .sl4 files (leave empty or NULL if none)
har_suffix <- "-WEL"   # Suffix for .har files
process_sl4_vars <- "sl4map"  # Leave it like this for default
process_har_vars <- "harmap"  # Leave it like this for default
subtotal_level <- FALSE  # Set TRUE if subtotals are included in your simulations

# Meta Data
mapping_info <- "Mix"  # Controls variable descriptions and units (see documentation)

# Output Format Setup
csv.output   <- "No"
stata.output <- "No"
r.output     <- "No"
txt.output   <- "No"
plot_data    <- TRUE   # Generate plot-ready outputs

# Output Formatting
sl4_convert_unit <- "mil2bil"  # Convert million to billion
har_convert_unit <- "mil2bil"
decimals         <- 2
rename_columns   <- TRUE       # Rename GTAP columns (e.g., "REG" → "Region")
add_scenario_ranking <- TRUE   # Add numeric rank to experiments

###################################
# DO NOT CHANGE BELOW THIS LINE
###################################

assign_default <- function(var_name, default_value, treat_null_as_missing = TRUE, treat_empty_string_as_missing = FALSE) {
  if (!exists(var_name)) {
    return(default_value)
  }
  
  val <- get(var_name)
  
  if (is.na(val)) return(default_value)
  if (treat_null_as_missing && is.null(val)) return(default_value)
  if (treat_empty_string_as_missing && identical(val, "")) return(default_value)
  
  return(val)
}

# Install packagfees if not already installed
if (!requireNamespace("devtools", quietly = TRUE)) {
  install.packages("devtools")
}

# Install GTAPViz from GitHub if not already installed
if (!requireNamespace("GTAPViz", quietly = TRUE)) {
  devtools::install_github("Bodysbobb/GTAPViz")
}

# Load the GTAPViz package
require(GTAPViz)

# 1. Default Directory
input.folder <- paste0(project.folder, "/in")
map.folder <- paste0(project.folder, "/map")
output.folder <- paste0(project.folder, "/out")

# 2. Default Input Files
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")

# 3. Suffix for Input Files
sl4_suffix <- assign_default("sl4_suffix", "", treat_empty_string_as_missing = FALSE)
har_suffix <- assign_default("har_suffix", "", treat_empty_string_as_missing = FALSE)

# 4. Filter Data
selected_regions <- if (exists("filter.map") && length(filter.map$Region) > 0) filter.map$Region else NULL
selected_sector  <- if (exists("filter.map") && length(filter.map$Sector) > 0) filter.map$Sector else NULL

# 5. Converting Units & Rename Columns
sl4_convert_unit <- assign_default("sl4_convert_unit", NULL)
har_convert_unit <- assign_default("har_convert_unit", NULL)
decimals <- assign_default("decimals", 4)
rename_columns <- assign_default("rename_columns", TRUE)

# 6. Scenario Number Labels Column
add_scenario_ranking <- assign_default("add_scenario_ranking", FALSE)

# 7. Data Extraction Methods
## Set default values if missing
sl4_extract_method <- assign_default("sl4_extract_method", "get_data_by_dims")
har_extract_method <- assign_default("har_extract_method", "get_data_by_var")

## Check if priority is missing when using group_data_by_dims
if (sl4_extract_method == "group_data_by_dims") {
  if (!exists("sl4_priority") || is.null(sl4_priority) || sl4_priority == "") {
    stop("Please define 'sl4_priority' for sl4_extract_method = 'group_data_by_dims'")
  }
}

if (har_extract_method == "group_data_by_dims") {
  if (!exists("har_priority") || is.null(har_priority) || har_priority == "") {
    stop("Please define 'har_priority' for har_extract_method = 'group_data_by_dims'")
  }
}

auto_gtap_data(
  # Input Main File Names
  experiment = experiment, 
  
  # Input File Suffixes
  sl4_suffix = sl4_suffix,
  har_suffix = har_suffix,
  
  # 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")
  mapping_info = mapping_info,
  sl4_mapping_info = sl4map,
  har_mapping_info = harmap,
  rename_columns = rename_columns,
  
  # Convert units (see `?convert_units`)
  sl4_convert_unit = sl4_convert_unit,
  har_convert_unit = har_convert_unit,
  
  # Region and Sector Filtering
  region_select = selected_regions,
  sector_select = selected_sector,
  
  # Data Extraction Process
  sl4_extract_method = sl4_extract_method,
  har_extract_method = har_extract_method,
  subtotal_level = subtotal_level,
  
  # If using `"group_data_by_dims"`, a `priority_list` is required. See `?HARplus::group_data_by_dims`.
  sl4_priority = sl4_priority,
  har_priority = har_priority,
  
  # Adding Scenario Ranking
  add_scenario_ranking = add_scenario_ranking,
  
  # 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"
)

This function is an advanced mode for fully configuring everything within the function itself. You must define all parameters manually. See ?auto_gtap_data for details.


# See ?auto_gtap_data

auto_gtap_data(
  # Input Main File Names
  experiment = experiment, 
  
  # Input File Suffixes
  sl4_suffix = sl4_suffix,
  har_suffix = har_suffix,
  
  # 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")
  mapping_info = mapping_info,
  sl4_mapping_info = sl4map,
  har_mapping_info = harmap,
  rename_columns = rename_columns,
  
  # Convert units (see `?convert_units`)
  sl4_convert_unit = sl4_convert_unit,
  har_convert_unit = har_convert_unit,
  
  # Region and Sector Filtering
  region_select = selected_regions,
  sector_select = selected_sector,
  
  # Data Extraction Process
  sl4_extract_method = sl4_extract_method,
  har_extract_method = har_extract_method,
  subtotal_level = subtotal_level,
  
  # If using `"group_data_by_dims"`, a `priority_list` is required. See `?HARplus::group_data_by_dims`.
  sl4_priority = sl4_priority,
  har_priority = har_priority,
  
  # Adding Scenario Ranking
  add_scenario_ranking = add_scenario_ranking,
  
  # 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"
)

Step 1: Project Setup

Directories and Input Files

1 Project Directory

1.1 project.folder

1.2 experiment

1.3 sl4_suffix / har_suffix

1.4 process_var

2 Output Formatting

2.1 mapping_info

2.2 output formats

2.3 plot_data

2.4 convert_unit / decimals

2.5 rename_columns

2.6 subtotal_level

2.7 add_scenario_ranking

Optional - Data Extraction

1.1 `project.folder`

1.2 `experiment`

1.3 `sl4_suffix / har_suffix`

1.4 `process_var`

2.1 `mapping_info`

2.2 `output formats`

2.3 `plot_data`

2.4 `convert_unit / decimals`

2.5 `rename_columns`

2.6 `subtotal_level`

2.7 `add_scenario_ranking`