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 usingbreakout_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 stateBreakout 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. Thepopulationshould be inmillions. - pcgdp_projection: An R data table or a path to a .csv file which has
columns
region,year,pcgdp. Thepcgdpshould be inthous 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
#> region year population
#> 1 Bangkok 1971 3.345901
#> 2 Bangkok 1972 3.414184
#> 3 Bangkok 1973 3.483862
#> 4 Bangkok 1974 3.554961
#> 5 Bangkok 1975 3.627511
#> 6 Bangkok 1976 3.701542
#> 7 Bangkok 1977 3.777084
#> 8 Bangkok 1978 3.854167
#> 9 Bangkok 1979 3.932823
#> 10 Bangkok 1980 4.013085
#> 11 Bangkok 1981 4.094985
#> 12 Bangkok 1982 4.178556
#> 13 Bangkok 1983 4.263832
#> 14 Bangkok 1984 4.350849
#> 15 Bangkok 1985 4.439642
#> 16 Bangkok 1986 4.530247
#> 17 Bangkok 1987 4.622701
#> 18 Bangkok 1988 4.717042
#> 19 Bangkok 1989 4.813308
#> 20 Bangkok 1990 4.911539
#> 21 Bangkok 1991 5.011775
#> 22 Bangkok 1992 5.114056
#> 23 Bangkok 1993 5.218424
#> 24 Bangkok 1994 5.324923
#> 25 Bangkok 1995 5.433595
#> 26 Bangkok 1996 5.544484
#> 27 Bangkok 1997 5.657637
#> 28 Bangkok 1998 5.773099
#> 29 Bangkok 1999 5.890917
#> 30 Bangkok 2000 6.011140
#> 31 Bangkok 2001 6.133816
#> 32 Bangkok 2002 6.258996
#> 33 Bangkok 2003 6.386731
#> 34 Bangkok 2004 6.517072
#> 35 Bangkok 2005 6.650074
#> 36 Bangkok 2006 6.785790
#> 37 Bangkok 2007 6.924275
#> 38 Bangkok 2008 7.065587
#> 39 Bangkok 2009 7.209783
#> 40 Bangkok 2010 7.356921
#> 41 Bangkok 2011 7.507062
#> 42 Bangkok 2012 7.660268
#> 43 Bangkok 2013 7.816600
#> 44 Bangkok 2014 7.976122
#> 45 Bangkok 2015 8.138900
#> 46 Bangkok 2020 8.305000
#> 47 Bangkok 2025 9.058789
#> 48 Bangkok 2030 9.779270
#> 49 Bangkok 2035 10.404681
#> 50 Bangkok 2040 10.958289
#> 51 Bangkok 2045 11.385714
#> 52 Bangkok 2050 11.745760
#> 53 Bangkok 2055 11.999071
#> 54 Bangkok 2060 12.208129
#> 55 Bangkok 2065 12.307004
#> 56 Bangkok 2070 12.355202
#> 57 Bangkok 2075 12.310853
#> 58 Bangkok 2080 12.231142
#> 59 Bangkok 2085 12.083059
#> 60 Bangkok 2090 11.911445
#> 61 Bangkok 2095 11.691495
#> 62 Bangkok 2100 11.457612
#> 63 Rest of Thailand 1971 26.002037
#> 64 Rest of Thailand 1972 26.532691
#> 65 Rest of Thailand 1973 27.074174
#> 66 Rest of Thailand 1974 27.626708
#> 67 Rest of Thailand 1975 28.190519
#> 68 Rest of Thailand 1976 28.765836
#> 69 Rest of Thailand 1977 29.352893
#> 70 Rest of Thailand 1978 29.951932
#> 71 Rest of Thailand 1979 30.563196
#> 72 Rest of Thailand 1980 31.186935
#> 73 Rest of Thailand 1981 31.823403
#> 74 Rest of Thailand 1982 32.472860
#> 75 Rest of Thailand 1983 33.135571
#> 76 Rest of Thailand 1984 33.811808
#> 77 Rest of Thailand 1985 34.501844
#> 78 Rest of Thailand 1986 35.205964
#> 79 Rest of Thailand 1987 35.924453
#> 80 Rest of Thailand 1988 36.657605
#> 81 Rest of Thailand 1989 37.405719
#> 82 Rest of Thailand 1990 38.169101
#> 83 Rest of Thailand 1991 38.948062
#> 84 Rest of Thailand 1992 39.742921
#> 85 Rest of Thailand 1993 40.554001
#> 86 Rest of Thailand 1994 41.381634
#> 87 Rest of Thailand 1995 42.226157
#> 88 Rest of Thailand 1996 43.087915
#> 89 Rest of Thailand 1997 43.967260
#> 90 Rest of Thailand 1998 44.864551
#> 91 Rest of Thailand 1999 45.780154
#> 92 Rest of Thailand 2000 46.714443
#> 93 Rest of Thailand 2001 47.667799
#> 94 Rest of Thailand 2002 48.640611
#> 95 Rest of Thailand 2003 49.633277
#> 96 Rest of Thailand 2004 50.646201
#> 97 Rest of Thailand 2005 51.679797
#> 98 Rest of Thailand 2006 52.734487
#> 99 Rest of Thailand 2007 53.810701
#> 100 Rest of Thailand 2008 54.908878
#> 101 Rest of Thailand 2009 56.029468
#> 102 Rest of Thailand 2010 57.172926
#> 103 Rest of Thailand 2011 58.339720
#> 104 Rest of Thailand 2012 59.530327
#> 105 Rest of Thailand 2013 60.745232
#> 106 Rest of Thailand 2014 61.984930
#> 107 Rest of Thailand 2015 63.249929
#> 108 Rest of Thailand 2020 64.540744
#> 109 Rest of Thailand 2025 65.081912
#> 110 Rest of Thailand 2030 65.238450
#> 111 Rest of Thailand 2035 64.979528
#> 112 Rest of Thailand 2040 64.260994
#> 113 Rest of Thailand 2045 63.182155
#> 114 Rest of Thailand 2050 61.805912
#> 115 Rest of Thailand 2055 60.290566
#> 116 Rest of Thailand 2060 58.654786
#> 117 Rest of Thailand 2065 56.885557
#> 118 Rest of Thailand 2070 54.992523
#> 119 Rest of Thailand 2075 53.039047
#> 120 Rest of Thailand 2080 51.039906
#> 121 Rest of Thailand 2085 49.050840
#> 122 Rest of Thailand 2090 47.060557
#> 123 Rest of Thailand 2095 45.119707
#> 124 Rest of Thailand 2100 43.204887
# Example format of gcambreakout::template_pcgdp_projection
# pcgdp should be in "thous 2005 USD/per capita"
gcambreakout::template_pcgdp_projection
#> region year pcgdp
#> 1 Bangkok 1971 3.736694
#> 2 Bangkok 1975 4.151882
#> 3 Bangkok 1980 4.613202
#> 4 Bangkok 1985 5.125780
#> 5 Bangkok 1990 5.695311
#> 6 Bangkok 1995 6.328124
#> 7 Bangkok 2000 7.031248
#> 8 Bangkok 2005 9.016968
#> 9 Bangkok 2010 10.742040
#> 10 Bangkok 2015 12.819406
#> 11 Bangkok 2020 16.030139
#> 12 Bangkok 2025 19.912423
#> 13 Bangkok 2030 24.240425
#> 14 Bangkok 2035 28.890297
#> 15 Bangkok 2040 33.983472
#> 16 Bangkok 2045 39.525512
#> 17 Bangkok 2050 45.482692
#> 18 Bangkok 2055 51.866997
#> 19 Bangkok 2060 58.635618
#> 20 Bangkok 2065 65.770917
#> 21 Bangkok 2070 73.237524
#> 22 Bangkok 2075 81.109397
#> 23 Bangkok 2080 89.302655
#> 24 Bangkok 2085 97.658508
#> 25 Bangkok 2090 106.212522
#> 26 Bangkok 2095 114.925911
#> 27 Bangkok 2100 123.863319
#> 28 Rest of Thailand 1971 2.531686
#> 29 Rest of Thailand 1975 2.812985
#> 30 Rest of Thailand 1980 3.125539
#> 31 Rest of Thailand 1985 3.472821
#> 32 Rest of Thailand 1990 3.858690
#> 33 Rest of Thailand 1995 4.287433
#> 34 Rest of Thailand 2000 4.763815
#> 35 Rest of Thailand 2005 6.109181
#> 36 Rest of Thailand 2010 7.277952
#> 37 Rest of Thailand 2015 8.685410
#> 38 Rest of Thailand 2020 10.860747
#> 39 Rest of Thailand 2025 13.431267
#> 40 Rest of Thailand 2030 16.276403
#> 41 Rest of Thailand 2035 19.314217
#> 42 Rest of Thailand 2040 22.618158
#> 43 Rest of Thailand 2045 26.197458
#> 44 Rest of Thailand 2050 30.018022
#> 45 Rest of Thailand 2055 34.098539
#> 46 Rest of Thailand 2060 38.395688
#> 47 Rest of Thailand 2065 42.913706
#> 48 Rest of Thailand 2070 47.611283
#> 49 Rest of Thailand 2075 52.556358
#> 50 Rest of Thailand 2080 57.673216
#> 51 Rest of Thailand 2085 62.882664
#> 52 Rest of Thailand 2090 68.185135
#> 53 Rest of Thailand 2095 73.581423
#> 54 Rest of Thailand 2100 79.088764Restore 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")