Modifying GCAM via the Data System

Adding a new region

Adding a new region to GCAM is fairly easy and only requires changing a few csv files. Note that you will need to start from the raw IEA data (not the pre-built data that comes with the gcamdata package) as this needs to be re-aggregated.

Step 1: Ensure you have the IEA data and CEDS proprietary data available.

• Copy IEA_EnergyBalances_2019.csv into the inst/extdata/energy folder.
• Copy the *_total_CEDS_emissions.csv (for each emissions species) in CEDS_Data into the inst/extdata/emissions/CEDS folder.

Step 2: Add the region to the GCAM region files.

• Update the GCAM_region_ID column of the iso_GCAM_regID.csv file in inst/extdata/common folder.
• Update the GCAM_region_names.csv file to include your new region number and name.

Example: If you are adding a new single country region, you would simply add 33 to the GCAM_region_ID column of the iso_GCAM_regID.csv for the country you want to separate. Then, you would add a new row to GCAM_region_names.csv with GCAM_region_ID equal to 33 and the region name of your choosing.

Step 3: Update region specific assumptions throughout the data system

• Add a row to each of the following files with assumptions for your region. Files that need changing:

1. extdata/aglu/A_bio_frac_prod_R.csv
2. extdata/aglu/A_soil_time_scale_R.csv
3. extdata/emissions/A_regions.csv
4. extdata/emissions/EPA_country_map.csv
5. extdata/energy/A23.subsector_interp_R.csv
6. extdata/energy/A_regions.csv
7. extdata/energy/offshore_wind_potential_scaler.csv

Example: If you are adding a new single country region, you need to add a row with 33 in the GCAM_region_ID column and fill in the necessary information in all other columns for all of these files.

Creating a new input file that requires a new header

If you are planning to create new xml files and the header you need is not currently listed in level2_data_names, then you should:

Step 1: Add your new header to both ModelInterface_headers.txt and level2_data_names in the data-raw/generate_package_data.R file.

Step 2: Regenerate the package data by sourcing the data-raw/generate_package_data.R

Step 3: Add the code needed to create your xml file.

If you try to do Step 3 before Step 2, the driver() will fail to run when generating package data. Generating the package data requires internal consistency between the LEVEL2_DATA_NAMES that are used in creating CSVs for the XML conversion and the existing package data (i.e., prior to re-building it). For this reason, to change an existing header (e.g., if we change minicam-energy-input to gcam-input), all instances in the code where the new or modified header(s) is (are) called need to be temporarily removed prior to re-generating package data.