mipplot-Manual-v1.md

In UTokyo-mip/mipplot: An Open-Source Tool for Visualization of Climate Mitigation Scenarios

R mipplot package

Developers: Diego SILVA HERRAN 1 , Jiayang WANG 2, Masahiro SUGIYAMA 2, Hiroto SHIRAKI 3.

1 Institute for Global Environmental Strategies (IGES), Japan.

2 Policy Alternatives Research Insititute (PARI), The University of Tokyo, Japan.

3 The University of Shiga Prefecture, Japan.

Outline

The mipplot tool produces plots for straightforward visualization of data from climate mitigation scenarios (also known as emission scenarios) generated by means of integrated assessment models (IAM) and energy-economic models. The tool can be applied to any dataset following the format adopted by data submissions contributing to IPCC’s assessment reports.

1. Introduction

This document describes the features of the mipplot tool, a tool for visualizing data from climate mitigation scenarios (also known as emission scenarios) generated by means of integrated assessment models (IAM) and energy-economic models. The tool is a package of scripts developed in “R” programming language (R version 3.4.0) in the “RStudio” software (version 1.0.143). It was developed to serve a two-fold purpose: gathering of IAM scenario data into a consistent dataset, and straightforward visualization of key data from multiple models. The approach adopted in the development of the tool can be potentially applied to any dataset that follows the Integrated Assessment Modeling Consortium (IAMC) data submission format. This format has been adopted by data submissions contributing to IPCC’s assessment reports. Moreover, the tool can be delivered as a hands-on tool for non-experts to visualize with minimum effort the information from mitigation scenarios.

2. Purpose

The initial purpose of the mipplot tool is to generate plots from emission scenario data with minimum effort from users. It has been developed assuming that users have little knowledge on the background of the models and methodologies used to generate such data. This tool uses the data from different models and scenarios generated for model intercomparison comparison (MIP) exercises. As such exercises are conducted on the assumption that data by different models is comparable, guaranteeing that the data submitted by all modeling teams are consistent on their own, and comply with a standard format is essential for the analyses. The tool can be used to check the list of variables submitted and missing, check the additivity of disaggregated variables to their corresponding totals, and generating plots of the variables.

3. Tool outline (input/output)

Figure 1 Schematic of the the tool with the flow of information.

Inputs

• Scenario data file: this file contains all data in the IAMC standard format for data submission based on a list of pre-defined variables.
• Rule table: this table lists the variables included in the scenario data, grouped into aggregated and disaggregated variables. It defines the aggregated variables as “left hand side” variables, and disaggregated variables as “right hand side” variables.

Processes

• Set up: install and import libraries.
• Input data preparation: edits the input data to table format suitable for diagnostics and plotting.
• Diagnostic plots: generate plots of the variables submitted.
• Variable submission check: generate list of variables submitted/missing.
• Additivity test: checks the additivity of disaggregated variables to their corresponding totals.

4. Outputs

• Diagnostic plots.
• List of submitted/missing variables.
• Results of the additivity test.

5. Software requirements and tool installation

The following softwares are needed for installation and operation of the tool.

Software

• R programming language: This is a software for scripting language. It can be downloaded for free from the R website.

• RStudio: This is a visual interface for developing and executing scripts developed in R language. It can be downloaded for free from the RStudio website.

Installing the package

Some R libraries containing built-in functions are required to install and operate the mipplot tool. They can be installed for free via R or RStudio with the following instructions.

Windows

1. Visit the release page on GitHub.

2. Download the latest zip file (binary package).

3. Start R.

4. Set working directory to where the downloaded file is in.

5. Run following commands.

install.packages("tidyverse")
install.packages("mipplot_0.1.0.zip", repos = NULL)

Mac OS

1. Visit the release page on GitHub.

2. Download the latest tar.gz file (source package).

3. Start R.

4. Set working directory to where the downloaded file is in.

5. Run following commands.

install.packages("tidyverse")
install.packages("mipplot_0.1.0.tar.gz", repos = NULL)

Ubuntu (or Debian based distribution)

1. Run the following commands:

sudo apt install build-essential gfortran g++ libcurl4-openssl-dev libxml2-dev libssl-dev

This commands install the library which tidyverse library depends.

1. Visit the release page on GitHub.

2. Download the latest tar.gz file (source package).

3. Start R.

4. Set working directory to where the downloaded file is in.

5. Run following commands.

install.packages("tidyverse")
install.packages("mipplot_0.1.0.tar.gz", repos = NULL)

6. Tool operation

Overall workflow

The tool is operated by first reading the input data file, and then by applying any of the plotting and diagnostic functions supported by the tool. All functions will be applied to the object defined when reading the input data. As long as all functions are applied to the same input data, and the session in RStudio is not terminated, there is no need to read the input data a second time.

Figure 2 Schematic of the workflow for operation of the tool.

Loading the input data

Read the input data with the readquitte function. If no file is specified, a sample dataset from the IPCC AR5 scenario database is loaded by default.

Creating plots from the input data

Several types of plots based on the input data can be generated. The plot types supported by the current version of the tool includes line, stacked area, stacked bar, and boxplot. Invoke plotting function Specify scope of data to plot: scenarios, models, regions, variables, periods (if needed). Specify plotting options: color, line, facet, etc. Enable output as pdf file.

Diagnosing integrity of the input data

Other operations (forthcoming?)

7. Tool structure

Libraries

• The packages (i.e. libraries) necessary for running the tool include “reshape2” (for transforming data tables from/to long to/from wide format), “stringr” (to manipulate strings), “openxlsx” (to read and write spreadsheet files in xlsx format), “ggplots” (to create plots), “data.table” (to read input data files), “dplyr” (to format and processing dataframes), “tibble” (to format and process dataframes), “readr”.

Read and format input data

• Read and process the input data: This process transforms an IAMC format data table into a format suitable for applying plotting functions in R programming language. It transform from wide table format (years in columns) to long table format (years as rows and only one column with values). Values in all columns, except for “period” (year) and “value”, are converted into factors. This process is partially compatible with read.quitte function of the quitte package. ```r mipplot_read_iamc (filename=NULL, sep=",", interactive=FALSE, DEBUG=T)

  - Input Arguments
    - **filename**: Path to a file containing scenario data in IAMC format.
    - **sep**: A character indicating the separator used in the input file.
    - **interactive**: open a dialog for selecting file if interactive=TRUE.
    - **DEBUG**: experimental.
  - Output variable
    - A dataframe in tibble format ("model, scenario, variable, unit, period, value")

  Example:
 ```r
mipplot_read_iamc(filename)

• Read table of additivity rule and adds column with id number

```r mipplot_read_ruletab(R_without_id)

  - Input Arguments
    - **R_without_id**: Path to a file containing data of additivity rule.
  - Output Variable
    - A dataframe of additivity rule ("ID, Left_side, Right_side")

 Example:
 ```r
mipplot_read_ruletab (R_without_id)

Plotting functions

• Area plot: stacked area plots using right-hand-side values of target additivity rule.

r mipplot_area ( D, R, region=levels(D$region), scenario=levels(D$scenario), facet_x=NULL, facet_y=NULL, PRINT_OUT=F, DEBUG=T, fontsize=20, color_code_specify=T) - Input Arguments - D: A dataframe of IAMC data in tibble format to produce area plots. - R: A dataframe of data aggregation rules (meta data). - region: A list of regions. - scenario: A list of scenario. - facet_x: facet_x - facet_y: facet_y - PRINT_OUT: set TRUE to generate PDF file. - DEBUG: set TRUE to show debug messages. - fontsize: font size of text. - color_code_specify: set FALSE if you apply default color palette. - Output Variable - A list of area plots.

Example:

mipplot_area(ar5_db_sample_data, ar5_db_sample_rule_table)

• Bar plot: stacked area plots using right-hand-side values of target additivity rule.

mipplot_bar (
    D, R,region = levels(D$region), xby = "scenario",
    target_year = levels(as.factor(D$period)),
    facet_x = NULL, facet_y = NULL, PRINT_OUT = F, DEBUG = T, fontsize = 20,
    color_code_specify = T)

• Input Arguments
  • D: A dataframe of IAMC data in tibble format to produce plots.
  • R: A dataframe of data aggregation rules (meta data).
  • region: A list of region.
  • xby: name of axis. the default setting is "scenario".
  • target_year: target year.
  • facet_x: facet_x
  • facet_y: facet_y
  • PRINT_OUT: set TRUE to generate A PDF file.
  • DEBUG: set TRUE to show debug messages.
  • fontsize: size of font in the output plot.
  • color_code_specify: set FALSE if you apply default color palette.
• Output Variable
  • A list of bar plots.

Example:

mipplot_bar(ar5_db_sample_data, ar5_db_sample_rule_table)

• Line plot: line plots of multiple selected scenarios/models.

mipplot_line ( D, region = levels(D$region), variable = levels(D$variable),
    colorby = "scenario", linetypeby = "model", shapeby = "model",
    scenario = levels(D$scenario), facet_x = NULL, facet_y = NULL, PRINT_OUT = F, DEBUG = T)

• Input Arguments
  • D: A dataframe of IAMC data in tibble format to produce plots.
  • region: A list of regions.
  • variable: A list of variables.
  • colorby: an axis for color setting.
  • linetypeby: an axis for line type setting.
  • shapeby: an axis for shape setting.
  • scenario: A list of cenarios.
  • facet_x: facet_x
  • facet_y: facet_y
  • PRINT_OUT: set TRUE to generate PDF files.
  • DEBUG: set TRUE to show debug messages.
• Output Variable
  • A list of line plots.

Example:

mipplot_line(ar5_db_sample_data)

• Box plot: box plots representing spread of data (minimum/maximum values, median, 25th/75th interquartiles, outliers) for a specific period.

mipplot_box ( D, region = levels(D$region), variable = levels(D$variable),
     target_year = levels(as.factor(D$period)), PRINT_OUT = F, DEBUG = T)

• Input Arguments
  • D: A dataframe of IAMC data in tibble format to produce plots.
  • region: A list of regions.
  • variable: A list of variables.
  • target_year: target year.
  • PRINT_OUT: set TRUE to generate PDF file.
  • DEBUG: set TRUE to show debug messages.
• Output Variable
  • A list of box plots.

Example:

mipplot_box(ar5_db_sample_data)

References

• IAMC AR5 Scenario Database, 2014. Available at: https://secure.iiasa.ac.at/web-apps/ene/AR5DB/

Appendix

Rule table AR5 vXX

AR5 scenario database description

See the Annex ii of the IPCC AR5, and the homepage of the IPCC AR5 database.

UTokyo-mip/mipplot documentation built on Aug. 7, 2021, 6:25 p.m.