Case Tutorial

Installation

Download and install:
- R (https://www.r-project.org/)
- R studio (https://www.rstudio.com/)
For Linux users, install following libraries:

sudo apt install build-essential libcurl4-gnutls-dev libxml2-dev libssl-dev
sudo apt-get install libxml2-dev

Open R studio:

install.packages('devtools')
devtools::install_github('JGCRI/rgcam')
devtools::install_github('JGCRI/plutus')

Example

This example will give you a step-by-step instruction on using the core functionality of plutus.

1. Download example dataset

Download GCAM sample XML database at http://doi.org/10.5281/zenodo.4641500
Unzip dataset to your desired location. Make sure the path is the one that holds the dataset (.basex files). In this example, the path to the dataset is: E:/plutus_example/IDBNexus_gcam5p3_HadGEM2-ES_rcp8p5

2. Prepare your own input data and assumptions

The default data and assumptions used in plutus can be found in GCAM v5.3 (See Table 1). However, if any of those files listed in Table 1 have been updated in your GCAM run, it is necessary to use the updated values in plutus as well. plutus uses argument gcamdataFile to specify the path to ALL of the updated files.

Table 1: Data and assumption files. “~\” represents the path to your GCAM v5.3 home folder.

Data or Assumption	Technology	Region	Data File in GCAM v5.3
Overnight capital costs	Electricity generation technologies	Global	~\input\gcamdata\outputs\L2233.GlobalIntTechCapital_elec.csv ~\input\gcamdata\outputs\L2233.GlobalTechCapital_elecPassthru.csv
Overnight capital costs	Cooling technologies	Global	~\input\gcamdata\outputs\L2233.GlobalIntTechCapital_elec_cool.csv ~\input\gcamdata\outputs\L2233.GlobalTechCapital_elec_cool.csv
Capacity factors	Electricity generation technologies	Global	~\input\gcamdata\outputs\L223.GlobalTechCapFac_elec.csv
Capacity factors	Intermittant technologies	Global	~\input\gcamdata\outputs\L223.GlobalIntTechCapFac_elec.csv
Capacity factors	Intermittant technologies	Regional	~\input\gcamdata\outputs\L223.StubTechCapFactor_elec.csv
Lifetime and steepness	Electricity generation technologies	Global	~\input\gcamdata\inst\extdata\energy\A23.globaltech_retirement.csv

Note: In this example, our GCAM sample dataset is based on the default data and assumptions, so we do not need to update those files in plutus.

3. Use `plutus::gcamInvest` to estimate stranded assets and electricity investments

Here are the core arguments we used in this example:

gcamdatabase: FULL path to the GCAM output XML database folder.
reReadData: If TRUE, plutus will read the GCAM database and create a queryData.proj file under the output directory.
scenOrigNames: Choose scenarios to read in. Default = ‘All’ will read all the scenarios.
regionsSelect: Choose regions to read in. Defaul = NULL will read all the regions.
saveData: If TRUE, plutus will save data by different aggregated classes.

# Load required packages
library(plutus)
library(dplyr)

# Set your directory based on the example dataset location
workdir <- 'E:/plutus_example/'

# provide path to the desired GCAM database folder that holds .basex files.
path_to_gcamdatabase <- file.path(workdir, 'IDBNexus_gcam5p3_HadGEM2-ES_rcp8p5')
# Specify the path to data file folder if any data files has been updated
# path_to_gcamdataFile <- 'E:/plutus_example/gcamdataFile'

# Use plutus::gcamInvest to calculate stranded assets and electricity investments
invest <- plutus::gcamInvest(gcamdatabase = path_to_gcamdatabase,
                             dataProjFile = file.path(workdir, 'outputs', 'dataProj.proj'),
                             dirOutputs = file.path(workdir, 'outputs'),
                             reReadData = T,
                             # gcamdataFile = path_to_gcamdataFile, # Use this argument if any data files has been updated
                             scenOrigNames = c('Reference'),
                             regionsSelect = c('USA', 'China'),
                             saveData = T)

4. Check outputs

plutus::gcamInvest returns a list containing:

data: a dataframe with the post-processed GCAM output showing stranded assets and electricity investments (see Table 2) by scenario, region, technology, and time period
dataAggParam: a dataframe with the data aggregated to the parameter
dataAggClass1: a dataframe with the data aggregated to class 1
dataAggclass2: a dataframe with the data aggregated to class 2
scenarios: A list of the scenarios
queries: A list of the queries used to extract the data

data contains the most detailed information. Check the structure and content of data and select the most relevant columns including scenario, region, param, class1 (= fuel types), x (= year), units, and value.

# Get dataframe with post-processed outputs for stranded assets and electricity investment
df_invest <- invest$data
# Check dataframe structure
str(df_invest)

## tibble [1,152 × 22] (S3: tbl_df/tbl/data.frame)
##  $ scenario     : chr [1:1152] "Reference" "Reference" "Reference" "Reference" ...
##  $ region       : chr [1:1152] "China" "China" "China" "China" ...
##  $ subRegion    : chr [1:1152] "China" "China" "China" "China" ...
##  $ param        : chr [1:1152] "elecNewCapCost" "elecNewCapCost" "elecNewCapCost" "elecNewCapCost" ...
##  $ sources      : chr [1:1152] "Sources" "Sources" "Sources" "Sources" ...
##  $ class1       : chr [1:1152] "Bioenergy" "Bioenergy" "Bioenergy" "Bioenergy" ...
##  $ class2       : chr [1:1152] "class2" "class2" "class2" "class2" ...
##  $ x            : num [1:1152] 2015 2020 2025 2030 2035 ...
##  $ xLabel       : chr [1:1152] "Year" "Year" "Year" "Year" ...
##  $ vintage      : chr [1:1152] "Vint_2015" "Vint_2020" "Vint_2025" "Vint_2030" ...
##  $ units        : chr [1:1152] "New Elec Cap Cost (Billion 2015 USD)" "New Elec Cap Cost (Billion 2015 USD)" "New Elec Cap Cost (Billion 2015 USD)" "New Elec Cap Cost (Billion 2015 USD)" ...
##  $ aggregate    : chr [1:1152] "sum" "sum" "sum" "sum" ...
##  $ classLabel1  : chr [1:1152] "Fuel" "Fuel" "Fuel" "Fuel" ...
##  $ classPalette1: chr [1:1152] "pal_metis" "pal_metis" "pal_metis" "pal_metis" ...
##  $ classLabel2  : chr [1:1152] "classLabel2" "classLabel2" "classLabel2" "classLabel2" ...
##  $ classPalette2: chr [1:1152] "classPalette2" "classPalette2" "classPalette2" "classPalette2" ...
##  $ origScen     : chr [1:1152] "Reference" "Reference" "Reference" "Reference" ...
##  $ origQuery    : chr [1:1152] "elec gen by gen tech and cooling tech and vintage" "elec gen by gen tech and cooling tech and vintage" "elec gen by gen tech and cooling tech and vintage" "elec gen by gen tech and cooling tech and vintage" ...
##  $ origUnits    : chr [1:1152] "billion 2015 USD" "billion 2015 USD" "billion 2015 USD" "billion 2015 USD" ...
##  $ origX        : num [1:1152] 2015 2020 2025 2030 2035 ...
##  $ value        : num [1:1152] 0 0 6.37 9.54 9.76 ...
##  $ origValue    : num [1:1152] 0 0 6.37 9.54 9.76 ...

# Select key variables
df_invest_sub <- df_invest %>% 
  dplyr::select(scenario, region, param, class1, x, units, value) %>% 
  dplyr::rename(fuel = class1,
                year = x)
head(df_invest_sub)

## # A tibble: 6 × 7
##   scenario  region param          fuel       year units                    value
##   <chr>     <chr>  <chr>          <chr>     <dbl> <chr>                    <dbl>
## 1 Reference China  elecNewCapCost Bioenergy  2015 New Elec Cap Cost (Bill…  0   
## 2 Reference China  elecNewCapCost Bioenergy  2020 New Elec Cap Cost (Bill…  0   
## 3 Reference China  elecNewCapCost Bioenergy  2025 New Elec Cap Cost (Bill…  6.37
## 4 Reference China  elecNewCapCost Bioenergy  2030 New Elec Cap Cost (Bill…  9.54
## 5 Reference China  elecNewCapCost Bioenergy  2035 New Elec Cap Cost (Bill…  9.76
## 6 Reference China  elecNewCapCost Bioenergy  2040 New Elec Cap Cost (Bill…  9.18

# Check out 8 parameters
unique(df_invest$param)

## [1] "elecNewCapCost"             "elecNewCapGW"              
## [3] "elecAnnualRetPrematureCost" "elecAnnualRetPrematureGW"  
## [5] "elecCumCapCost"             "elecCumCapGW"              
## [7] "elecCumRetPrematureCost"    "elecCumRetPrematureGW"

There are eight different parameters in the output showing stranded assets or electricity investments in terms of monetary value (Billion 2010 USD) or installed capacity (GW). The detailed descriptions are in Table 2. GCAM v5.3 is operated in five-years time step with 2015 as the final calibration year (base year). Annual value is the value calculated at each time step. Cumulative value represents the cumulative total over five-year time step.

Table 2: Descriptions of output parameters for stranded assets and electricity investments.