Author: U-Tokyo mipplot team
Date: 2021-05-17

# First steps with the mipplot package

#### U-Tokyo mipplot team

#### 2021-05-17

## Summary

The `mipplot` package is an `R` package for visualizing data in the IAMC template format.

This vignette introduces the basic features of the `mipplot` package.

## Data

This vignette uses a subset of the SR1.5 data. This data is included in the `mipplot` package and does not need to be downloaded separately.

## load library

Load the `mipplot` and `tidyverse` packages.

    library(mipplot)
    library(tidyverse)

## load sample data

The SR1.5 subset data that comes with the `mipplot` package can be accessed under the name `mipplot::sr15_sample_data`. Let’s take a look at what’s inside.

    sr15_sample_data
    #> # A tibble: 396,425 x 7
    #>    model       scenario region variable                unit         period value
    #>    <fct>       <fct>    <fct>  <fct>                   <fct>         <int> <dbl>
    #>  1 AIM/CGE 2.0 SSP1-19  World  Emissions|CO2           Mt CO2/yr      2000    NA
    #>  2 AIM/CGE 2.0 SSP1-19  World  Final Energy            EJ/yr          2000    NA
    #>  3 AIM/CGE 2.0 SSP1-19  World  Population              million        2000    NA
    #>  4 AIM/CGE 2.0 SSP1-19  World  Price|Carbon            US$2010/t C~   2000    NA
    #>  5 AIM/CGE 2.0 SSP1-19  World  Primary Energy          EJ/yr          2000    NA
    #>  6 AIM/CGE 2.0 SSP1-19  World  Primary Energy|Biomass  EJ/yr          2000    NA
    #>  7 AIM/CGE 2.0 SSP1-19  World  Primary Energy|Coal     EJ/yr          2000    NA
    #>  8 AIM/CGE 2.0 SSP1-19  World  Primary Energy|Fossil   EJ/yr          2000    NA
    #>  9 AIM/CGE 2.0 SSP1-19  World  Primary Energy|Gas      EJ/yr          2000    NA
    #> 10 AIM/CGE 2.0 SSP1-19  World  Primary Energy|Geother~ EJ/yr          2000    NA
    #> # ... with 396,415 more rows

The data is in `tibble` format. It contains the following columns: `model`, `scenario`, `region`, `variable`, `unit`, `period`, and `value`.

In addition, to read another data from a file, do the following.

    iamc_data <- mipplot_read_iamc("path_to_data.csv")

Check the list of models included in the data.

    sr15_sample_data$model %>% levels
    #> [1] "AIM/CGE 2.0"           "GCAM 4.2"              "IMAGE 3.0.1"
    #> [4] "MESSAGE-GLOBIOM 1.0"   "MESSAGEix-GLOBIOM 1.0" "REMIND-MAgPIE 1.5"
    #> [7] "WITCH-GLOBIOM 3.1"

Check the list of scenarios.

    sr15_sample_data$scenario %>% levels
    #>  [1] "SSP1-19"         "SSP1-26"         "SSP1-34"         "SSP1-45"
    #>  [5] "SSP1-Baseline"   "SSP2-19"         "SSP2-26"         "SSP2-34"
    #>  [9] "SSP2-45"         "SSP2-60"         "SSP2-Baseline"   "SSP3-34"
    #> [13] "SSP3-45"         "SSP3-60"         "SSP3-Baseline"   "SSP4-26"
    #> [17] "SSP4-34"         "SSP4-45"         "SSP4-Baseline"   "SSP5-26"
    #> [21] "SSP5-34"         "SSP5-45"         "SSP5-60"         "SSP5-Baseline"
    #> [25] "SSP4-60"         "SSP5-19"         "LowEnergyDemand" "SSP4-19"

Check the list of regions.

    sr15_sample_data$region %>% levels
    #> [1] "World"

Let’s check the list of variables.

    sr15_sample_data %>% select(variable, unit) %>% distinct
    #> # A tibble: 35 x 2
    #>    variable                  unit
    #>    <fct>                     <fct>
    #>  1 Emissions|CO2             Mt CO2/yr
    #>  2 Final Energy              EJ/yr
    #>  3 Population                million
    #>  4 Price|Carbon              US$2010/t CO2
    #>  5 Primary Energy            EJ/yr
    #>  6 Primary Energy|Biomass    EJ/yr
    #>  7 Primary Energy|Coal       EJ/yr
    #>  8 Primary Energy|Fossil     EJ/yr
    #>  9 Primary Energy|Gas        EJ/yr
    #> 10 Primary Energy|Geothermal EJ/yr
    #> # ... with 25 more rows

## Data Filtering

This section explains how to filter data, using the example of extracting only models that contain `SSP2` scenarios.

    sr15_sample_data %>%
      filter(str_detect(scenario, "^SSP2")) %>%
      select(model, scenario) %>% distinct
    #> # A tibble: 34 x 2
    #>    model       scenario
    #>    <fct>       <fct>
    #>  1 AIM/CGE 2.0 SSP2-19
    #>  2 AIM/CGE 2.0 SSP2-26
    #>  3 AIM/CGE 2.0 SSP2-34
    #>  4 AIM/CGE 2.0 SSP2-45
    #>  5 AIM/CGE 2.0 SSP2-60
    #>  6 AIM/CGE 2.0 SSP2-Baseline
    #>  7 GCAM 4.2    SSP2-19
    #>  8 GCAM 4.2    SSP2-26
    #>  9 GCAM 4.2    SSP2-34
    #> 10 GCAM 4.2    SSP2-45
    #> # ... with 24 more rows

The `"^SSP2"` given to the `str_detect` function is called a regular expression. The `"^"` stands for the beginning of a sentence, and the regular expression “^SSP2”" means to check if the string starts with “SSP2”.

`distinct` is a function that removes duplicate data.

Next, let’s extract the list of variables under Secondary Energy|Electricity|.

“|” has a special meaning in regular expressions, so to search for it we must use something like “\|”. This is called escaping.

    sr15_sample_data %>%
      filter(str_detect(variable, "^Secondary Energy\\|Electricity\\|")) %>%
      select(variable) %>%
      distinct
    #> # A tibble: 10 x 1
    #>    variable
    #>    <fct>
    #>  1 Secondary Energy|Electricity|Biomass
    #>  2 Secondary Energy|Electricity|Coal
    #>  3 Secondary Energy|Electricity|Gas
    #>  4 Secondary Energy|Electricity|Geothermal
    #>  5 Secondary Energy|Electricity|Hydro
    #>  6 Secondary Energy|Electricity|Non-Biomass Renewables
    #>  7 Secondary Energy|Electricity|Nuclear
    #>  8 Secondary Energy|Electricity|Oil
    #>  9 Secondary Energy|Electricity|Solar
    #> 10 Secondary Energy|Electricity|Wind

## Visualization with interactive tool

Let’s use the interactive interface of `mipplot` to filter and visualize the data.

### line plot

The first step is to perform a line plot, which can be done as follows:

    mipplot_interactive_line(sr15_sample_data)

You will then see a screen like the one below.

Select the various conditions and plot the graph.

The R code for reproducing the graph will be displayed on the screen. You can copy and paste it to edit the plot as shown below.

    data_subset <- sr15_sample_data %>%
      filter( model %in% c("AIM/CGE 2.0", "GCAM 4.2", "IMAGE 3.0.1") ) %>%
      filter(2000 <= period) %>%
      filter(period <= 2100)

    mipplot_line(
      data_subset,
      variable = c("Emissions|CO2"),
      scenario = c("SSP3-34", "SSP3-45", "SSP3-60", "SSP3-Baseline"),
      region = c("World"),
      legend = TRUE,
      language = 'en')[[1]]

### bar plot

Next, we will create a bar plot. Since bar plot needs a rule table, we will use the rule `ar5_db_sample_rule_table` for AR5.

    mipplot_interactive_bar(sr15_sample_data, ar5_db_sample_rule_table)

On the screen you will see the R code to reproduce the plot. Copy and paste this to edit the plot as shown below.

    data_subset <- sr15_sample_data %>%
      filter(variable %in% c("Primary Energy", "Primary Energy|Coal", "Primary Energy|Gas", "Primary Energy|Oil", "Primary Energy|Nuclear", "Primary Energy|Hydro", "Primary Energy|Biomass", "Primary Energy|Solar", "Primary Energy|Wind", "Primary Energy|Geothermal", "Primary Energy|Ocean")) %>%
      filter(model %in% c("AIM/CGE 2.0", "GCAM 4.2", "IMAGE 3.0.1")) %>%
      filter(scenario %in% c("SSP3-34", "SSP3-45", "SSP3-60", "SSP3-Baseline"))

    mipplot_bar(data_subset, ar5_db_sample_rule_table,
      region = c("World"),
      target_year = 2050,
      one_hundred_percent_stacked = FALSE,
      language = 'en')[[1]]

### area plot

Since area plot also requires a rule, we will use the rule `ar5_db_sample_rule_table` for AR5.

    mipplot_interactive_area(sr15_sample_data, ar5_db_sample_rule_table)

On the screen you will see the R code to reproduce the plot. Copy and paste this to edit the plot as shown below.

    data_subset <- sr15_sample_data %>%
      filter(variable %in% c("Secondary Energy|Electricity", "Secondary Energy|Electricity|Coal", "Secondary Energy|Electricity|Gas", "Secondary Energy|Electricity|Oil", "Secondary Energy|Electricity|Nuclear", "Secondary Energy|Electricity|Hydro", "Secondary Energy|Electricity|Biomass", "Secondary Energy|Electricity|Solar", "Secondary Energy|Electricity|Wind", "Secondary Energy|Electricity|Geothermal", "Secondary Energy|Electricity|Ocean")) %>%
      filter(model %in% c("AIM/CGE 2.0", "GCAM 4.2", "IMAGE 3.0.1")) %>%
      filter(2000 <= period) %>%
      filter(period <= 2100)

    mipplot_area(data_subset, ar5_db_sample_rule_table,
      region = c("World"),
      scenario = c("SSP3-Baseline"),
      one_hundred_percent_stacked = FALSE,
      language = 'en')[[1]]

## Output in another language

So far, we have plotted in English, but in addition to this, we can plot in Chinese (Simplified), Chinese (Traditional), Japanese, and Spanish.

All plots so far have specified `language = "en"` (English), so replace this with, for example, the following:

    data_subset <- sr15_sample_data %>%
      filter(variable %in% c("Secondary Energy|Electricity", "Secondary Energy|Electricity|Coal", "Secondary Energy|Electricity|Gas", "Secondary Energy|Electricity|Oil", "Secondary Energy|Electricity|Nuclear", "Secondary Energy|Electricity|Hydro", "Secondary Energy|Electricity|Biomass", "Secondary Energy|Electricity|Solar", "Secondary Energy|Electricity|Wind", "Secondary Energy|Electricity|Geothermal", "Secondary Energy|Electricity|Ocean")) %>%
      filter(model %in% c("AIM/CGE 2.0", "GCAM 4.2", "IMAGE 3.0.1")) %>%
      filter(2000 <= period) %>%
      filter(period <= 2100)

    mipplot_area(data_subset, ar5_db_sample_rule_table,
      region = c("World"),
      scenario = c("SSP3-Baseline"),
      one_hundred_percent_stacked = FALSE,
      language = 'jp')[[1]]  # <--------------- We changed here

The following table shows the languages and language codes that can be set.

language | language code
--- | ---
English | en
Chinese (Simplified) | zh-cn
Chinese (Traditional) | zh-tw
Japanese | jp
Spanish | es

## Output to PDF file

To output an image to a PDF file, do the following:

    data_subset <- sr15_sample_data %>%
      filter(variable %in% c("Secondary Energy|Electricity", "Secondary Energy|Electricity|Coal", "Secondary Energy|Electricity|Gas", "Secondary Energy|Electricity|Oil", "Secondary Energy|Electricity|Nuclear", "Secondary Energy|Electricity|Hydro", "Secondary Energy|Electricity|Biomass", "Secondary Energy|Electricity|Solar", "Secondary Energy|Electricity|Wind", "Secondary Energy|Electricity|Geothermal", "Secondary Energy|Electricity|Ocean")) %>%
      filter(model %in% c("AIM/CGE 2.0", "GCAM 4.2", "IMAGE 3.0.1")) %>%
      filter(2000 <= period) %>%
      filter(period <= 2100)

    # Save plot to `graph` variable
    graph <- mipplot_area(data_subset, ar5_db_sample_rule_table,
      region = c("World"),
      scenario = c("SSP3-Baseline"),
      one_hundred_percent_stacked = FALSE,
      language = 'zh-cn')[[1]]

    # Give `graph` to `mipplot_print_pdf`
    # mipplot_print_pdf(graph)

This will bring up a dialog box to save the file. You can save the file as a PDF file.