In xavier-gutierrez/validation_figures: Restructures Rgcam Project Files and Plots Validation Figures

knitr::opts_chunk$set(
    message = FALSE,
    warning = FALSE,
    collapse = TRUE,
    comment = "#>"
)

This package automates Model Validation figures used for developinging JGCRI's Global Change Assessment Model (GCAM). In order to initialize a figure generating object, the user must provide an rgcam project file, a scenario mapping file, and a list of transformation functions.

rgcam project file

The rgcam project file must contain the scenarios and queries you want to generate figures for. See JGCRI's rgcam package documentation for how to query a database and save a project file.

library(rgcam)
library(DevelopmentVerification)
library(magrittr)
proj <- system.file("extdata", "project.dat", package="DevelopmentVerification") %>% 
  loadProject()
# scenarios stored in project file
names(proj)
# queries stored in first scenario
names(proj[[1]])

scenario mapping file

For a full validation between two branches of GCAM, we must map the scenarios in our project file to their Shared Socioeconomic Pathway (SSP), radiative forcing target, and branch. The object generator in this package takes as input a mapping file which specifies these features for each scenario, as named in the GCAM database and stored in the rgcam project file.

map <- system.file("map-files", "scen-mapping.csv", package="DevelopmentVerification") %>%
  read.csv()
head(map)

transformation functions

Transformation functions are applied during initialization of the figure generating object, and are used primarily to aggregate a query or map to a different set of sectors/technologies. Transformation functions must be provided by the user.

In order to verify what columns you want to aggregate to/over, it's recommended you inspect the output of your desired query using Model Interface.

Some queries are, by convention, mapped to a smaller set of sectors or technologies for clarity. For example, Electricity generation by technology (inc solar roofs) uses the following transformation function

library(dplyr)
group.el <- function(df) {

  # maps from GCAM-native technologies to more aggregated set of technologies
  map.tech <- system.file("map-files", "elec_map.csv", package="DevelopmentVerification") %>%
    read.csv() 

  # Attach all mapping files to query-data
  df <- df %>%
    dplyr::rename(rgcam = scenario) %>%
    left_join(map.tech, by=c("technology")) %>% # agg.tech
    left_join(map, by = c("rgcam")) %>% # scenario, forcing, branch
    select(-rgcam)

  # aggregate to regional
  df.region <- df %>% 
    group_by(Units, scenario, forcing, branch, year, agg.tech, region) %>%
    summarise(value = sum(value)) %>%
    ungroup()

  # get global aggregate 
  df.global <- df %>% 
    group_by(Units, scenario, forcing, branch, year, agg.tech) %>%
    summarise(value = sum(value)) %>%
    ungroup() %>%
    mutate(region = "Global")

  # return regional & global query-data
  rbind(df.region, df.global)
}

In the absence of any mapping, we can more generically generate transformation functions using quosures.

group.quosure <- function(column) {

  # look-up value of column, convert to quosure
  column <- enquo(column)

  group.column <- function(df) { # column in parent function env, so will not be an input for returned function

  # Attach all mapping files to query-data
    df <- df %>%
      rename(rgcam = scenario) %>%
      left_join(map, by = c("rgcam")) %>%
      select(-rgcam)

    # aggregate to regional
    df.region <- df %>% 
      # unquote quosure using !! operator
      group_by(Units, scenario, forcing, branch, year, region, (!!column)) %>% 
      summarise(value = sum(value)) %>%
      ungroup()

    # get global aggregate 
    df.global <- df %>% 
      group_by(Units, scenario, forcing, branch, year, (!!column)) %>%
      summarise(value = sum(value)) %>%
      ungroup() %>%
      mutate(region = "Global")

    # return regional & global query-data
    rbind(df.region, df.global)

  }
  return(group.column)

} # returns a function

The group.quosure() functional returns a function that will aggregate to the indicated column. For example, if we know that the most detailed we need our query to be is the sector level, we can generate a transformation function that aggregates over subsector and/or technology: group.sector <- group.quosure(sector).

Ultimately, your transformation functions should be stored in a named list

transf <- list("Electricity generation by technology (inc solar roofs)" = group.el)

Initializing the figure generator

figureGenerator <- GCAMFigs(proj, transf)

Generating/Saving Validation Figures

The figure generator can produce two types of plots, using lineplot() and barchart(). You must provide the name of the query stored in figureGenerator for which you wish to generate a plot. The plot defaults to global unless you provide the name of a region.

query <- "Electricity generation by technology (inc solar roofs)"
region <- "USA"
lineplot(figureGenerator, query, region)[[1]]

Because barcharts for two branches can't be printed on the same axes, you must also provide the radiative forcing target as an argument in the barchart() function.

target <- "Ref"
barchart(figureGenerator, query, target, region)[[1]]

The output of these two functions is a list containing (1) the validating figure and (2) the name of the plot. This output can be used to programatically save validation figures for all queries with the following code

setwd('/path/to/dir/')
region <- "USA"
lapply(names(figureGenerator), function(query) {
   out <- lineplot(figureGenerator, query, region)
  ggsave(paste0(getwd(), out[[2]], ".png" ),
         plot = out[[1]],
         device = "png")
})

xavier-gutierrez/validation_figures documentation built on May 24, 2019, 9:58 p.m.