In JGCRI/rgcambreakout: gcambreakout

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
options(rmarkdown.html_vignette.check_title = FALSE)

Pre-requisites

Before running gcambreakout you will need:

• A running version of GCAM version 5.4
• IEA_EnergyBalances_2019.csv file placed in the ./input/inst/extdata/energy
• CEDS data placed in input/gcamdata/inst/extdata/emissions/CEDS
• NOTE: The CEDS data and IEA_EnergyBalances_2019.csv is proprietary data and only accesible to internal JGCRI staff at https://stash.pnnl.gov/scm/jgcri/gcam-proprietary-data.

Overview

gcambreakout works by editing the raw input files that define the regional structure in the gcamdata system. gcamdata is a folder inside every version of GCAM that contains all the input data and R code that is required to create the XML files that go into GCAM. The following files are edited with new regions added to them:

• ./input/gcamdata/inst/extdata/common/iso_GCAM_regID.csv
• ./input/gcamdata/inst/extdata/common/GCAM_region_names.csv
• ./input/gcamdata/inst/extdata/aglu/A_bio_frac_prod_R.csv
• ./input/gcamdata/inst/extdata/aglu/A_soil_time_scale_R.csv
• ./input/gcamdata/inst/extdata/emissions/A_regions.csv
• ./input/gcamdata/inst/extdata/energy/A23.subsector_interp_R.csv
• ./input/gcamdata/inst/extdata/energy/A_regions.csv
• ./input/gcamdata/inst/extdata/energy/offshore_wind_potential_scaler.csv

Once these files have been changed the gcamdata system must be re-built and the driver function has to be re-run to re-generated all the XML files. gcambreakout has the following functions:

• breakout_regions() : Used to breakout countries from the existing 32 regions in GCAM Core. Countries chosen must come from the same parent region.
• breakout_city(): Used to breakout cities from any existing GCAM region, including new regions that are created using breakout_regions()
• restore(): Used to restore the original files if desired (OPTIONAL)

Note: Broken out regions will not have electricity trade with other regions.

Breakout New Regions

The breakout_regions() function can be used to breakout new regions in GCAM. Users can breakout a single new region composed of one or more countries or several new regions each composed of one or more countries. The new region name can be any name the user wants however the countries that make up the new region must be one of the countries listed in: ./input/gcamdata/inst/extdata/common/iso_GCAM_regID.csv file. The following examples show how to breakout a single and multiple new regions composed of single and multiple countries.

library(gcambreakout); library(dplyr)

# Set the path to your ./input/gcamdata folder"
gcamdataFolderx <- "FULL_PATH_ADDRESS/gcam-core/input/gcamdata" # Example "C:/gcam-core/input/gcamdata" 

# Check the list of countries in ./input/gcamdata/inst/extdata/common/iso_GCAM_regID.csv
countries_allowed <- read.csv(paste0(gcamdataFolderx,"/inst/extdata/common/iso_GCAM_regID.csv"), comment.char = '#', header=T); countries_allowed$country_name
current_GCAM_regions <- read.csv(paste0(gcamdataFolderx,"/inst/extdata/common/GCAM_region_names.csv"), comment.char = '#', header=T); current_GCAM_regions


#-----------------------------------------------------------------
# Breakout a new region for Spain with a single country Spain
#-----------------------------------------------------------------
breakout_regions(gcamdataFolder = gcamdataFolderx,
         regionsNew = c("Spain"),
         countriesNew = c("Spain"))
# Users can confirm that a new region has been added by opening the .csv file: ./input/gcamdata/inst/extdata/common/GCAM_region_names.csv
# restore(gcamdataFolder = gcamdataFolderx)  # (OPTIONAL) Uncomment this line and restore the datasystem to original state


#-----------------------------------------------------------------
# Breakout a new custom region called "Peru_Chile" with both Peru and Chile
#-----------------------------------------------------------------
breakout_regions(gcamdataFolder = gcamdataFolderx,
         regionsNew = c("Peru_Chile"),
         countriesNew = c("Peru","Chile"))
# Users can confirm that a new region has been added by opening the .csv file: ./input/gcamdata/inst/extdata/common/GCAM_region_names.csv
# restore(gcamdataFolder = gcamdataFolderx)  # (OPTIONAL) Uncomment this line and restore the datasystem to original state


#-----------------------------------------------------------------
# Breakout two new regions: One for Peru and One for Chile with each having its own single country within it.
#-----------------------------------------------------------------
breakout_regions(gcamdataFolder = gcamdataFolderx,
         regionsNew = c("Peru","Chile"),
         countriesNew = c("Peru","Chile"))
# Users can confirm that a new region has been added by opening the .csv file: ./input/gcamdata/inst/extdata/common/GCAM_region_names.csv
# restore(gcamdataFolder = gcamdataFolderx)  # (OPTIONAL) Uncomment this line and restore the datasystem to original state


#-----------------------------------------------------------------
# Breakout two new regions: One for a combined "Peru_Chile" with Peru and Chile, and one for "Spain_France" with Spain and France
#-----------------------------------------------------------------

# NOTE: In this case the countriesNew must be a list!!

breakout_regions(gcamdataFolder = gcamdataFolderx,
         regionsNew = c("Peru_Chile",
                        "Spain_France"),
         countriesNew = list(c("Peru","Chile"),
                             c("Spain","France")))
# Users can confirm that a new region has been added by opening the .csv file: ./input/gcamdata/inst/extdata/common/GCAM_region_names.csv
# restore(gcamdataFolder = gcamdataFolderx)  # (OPTIONAL) Uncomment this line and restore the datasystem to original state

Breakout New Subregions

To breakout subregions (e.g.provinces, states, cities) users need to provide the following:

• region: The parent region from which the subregions are being broken out
• pop_projection: An R data table or a path to a .csv file which has columns region, year, population. The population should be in millions.
• pcgdp_projection: An R data table or a path to a .csv file which has columns region, year, pcgdp. The pcgdp should be in thous 2005 USD per capita

The region column in the tables above should include each new subregion as well as a region named "Rest of PARENT_REGION_NAME". Example tables are provided as gcambreakout::template_pcgdp_projection and gcambreakout::template_pop_projection for breaking out Bangkok from the larger Thailand region.

# This will only work if after Thailand has been broken out as a separate region
breakout_subregion(gcamdataFolder = gcamdataFolderx,
                   region = "Thailand",
                   pop_projection = gcambreakout::template_pop_projection),
                   pcgdp_projection = gcambreakout::template_pcgdp_projection)

# Example format of gcambreakout::template_pop_projection
# Population should be in "millions"
gcambreakout::template_pop_projection

# Example format of gcambreakout::template_pcgdp_projection
# pcgdp should be in "thous 2005 USD/per capita"
gcambreakout::template_pcgdp_projection

Restore Original Files

Users can also restore back to the original files by running the following code. This will replace the newly created files with the versions appended with '_Original' and delete the appended files. The gcamdata system will have to be rebuilt using 'install & restart' from R Studio once again followed by driver().

library(gcambreakout)
restore(gcamdataFolder = "PATH_TO_GCAM_FOLDER/input/gcamdata")

JGCRI/rgcambreakout documentation built on Nov. 30, 2023, 1:55 a.m.