The function compareScenariosLimes() of the limes package is based on the compareScenarios() function from the remind2 package and adapts it to the needs of the LIMES model [NB: compareScenarios() has now been updated to compareScenarios2()]. It can be used to visually compare the results of multiple runs of the LIMES model. See also vignette("compareScenarios2") from which this vignette is largely copied.

It can be called via the output.R script in the LIMES model: Execute Rscript output.R in the LIMES folder, select the scenarios you are interested in, then select extra and scenarioComparison.

The function reads the results from the output-mif-files (in the LIMES folder after runs are completed, i.e., the files output/<scenario_folder>/LIMES_generic_<scenario>.mif). Using this data, a document containing many plots is created and written as a PDF- or HTML-file. See ?limes::compareScenariosLimes for information on how to call the function with the appropriate arguments.

Internally, compareScenariosLimes() calls rmarkdown::render() on certain Rmarkdown-files (Rmd-files). Rmd-files may contain R-code (e.g., for creating plots) as well as descriptive text (in this case, mostly section titles). The Rmd-files to be rendered are part of the limes-package. In the development state of the package, they can be found in the folder inst/markdown/compareScenariosLimes/. To be more precise, rmarkdown::render() is called on cs2_main.Rmd in this folder, which includes other Rmd-files - one for each section of the output document. The loading and preprocessing of data happens in cs2_main.Rmd; the section Rmd-files mostly call plot functions.

Aside from HTML- and PDF-documents as output, compareScenariosLimes() also allows to obtain a copy of the Rmd-files needed to create these outputs (by setting the argument outputFormat = "Rmd"). Rendering the resulting Rmd-files to PDF or HTML yields the same documents as calls to compareScenariosLimes() with outputFormat = "PDF" or "HTML". The advantage of being able to access these Rmd-files is the possibility to change the plotting code without changing the code of the limes-package. Moreover, Rmd-files can be used interactively in RStudio.

Local Use and mif-Files

compareScenariosLimes() with default settings can be called automatically after a bundle of runs on the cluster has finished or manually via Rscript output.R. It can also be called directly as a function of the R-package limes, e.g.,

library(limes)
compareScenariosLimes(
  mifScen = c("path/to/Base.mif", "path/to/NDC.mif"),
  outputFile = "compareScenariosLimesExample")

To do this locally on our computer, we need some mif files to compare. One possibility is to adapt and execute the following script to download the newest modeltest files.

library(tidyverse)
library(ssh)
# TODO: Adapt the following three lines!
keyfile <- "path/to/ssh/private/key/.ssh/id_rsa"
username <- "username"
out_path <- "path/to/where/mifs/will/be/downloaded/"
# path on the cluster where to search for mifs:
path <- "/p/projects/remind/modeltests/output/"
# Connect to the cluster and get the file names of the newest modeltest mifs.
session <- ssh_connect(paste0(username, "@cluster.pik-potsdam.de"), keyfile = keyfile)
out <- ssh_exec_internal(session, paste("ls", path))
filenames <- out$stdout %>%
  rawToChar() %>%
  str_split("\n", simplify = TRUE) %>%
  str_subset("^[a-zA-Z0-9-]+_\\d{4}-\\d{2}-\\d{2}_\\d{2}\\.\\d{2}\\.\\d{2}$")
new_file_data <- filenames %>%
  str_split("_", simplify = TRUE) %>%
  matrix(ncol = 3, dimnames = list(NULL, c("name", "date", "time"))) %>%
  as_tibble() %>%
  bind_cols(filename = filenames) %>%
  mutate(date = as.Date(date)) %>%
  filter(date >= max(date) - 2)
  
new_files <- paste0(path, new_file_data$filename, "/LIMES_generic_", new_file_data$name, ".mif")
walk(new_files, scp_download, session = session, to = out_path) # download scenario mifs
hist_path <- paste0(path, new_file_data$filename[1], "/historical.mif")
scp_download(session = session, hist_path, to = out_path) # download historical.mif
ssh_disconnect(session)

Interactive Use of the Rmd-files

In this section, we assume that we do not want to change the package limes. But we may want to make changes to the compareScenarios output locally.

We call limes::compareScenariosLimes() with outputFormat = "Rmd" to obtain a (modified) copy of the Rmd-files.

library(limes)
compareScenariosLimes(
  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif", "path/to/scen3.mif"), # TODO.
  outputDir = "path/to/where/rmds/should/be/copied/to", # TODO.
  outputFormat = "Rmd",
  # Add current time as output name to not overwrite other things:
  outputFile = format(Sys.time(), "CompScen2-%Y%m%d-%H%M%S"))

The code in these Rmd-files is structured in chunks and each chunk can be run separately by clicking on its play-button. We first open cs2_main.Rmd. At the end of the file, there is a chunk


``` r
# CLICK "RUN ALL CHUNKS ABOVE" HERE TO PREPARE THE ENVIRONMENT
```

Clicking on the triangle above bar-button on the right executes all chunks above and by that loads and prepares the data for plotting. After that one can open any section-Rmd-file and execute a chunk to create the respective plots. The plots should appear in RStudio inside the Rmd-file below the chunk.

Workflow for Adding a new Plot to compareScenariosLimes

If not done already, fork https://github.com/pik-piam/limes.
In your personal github limes repository, create a new branch.
Clone the repository and switch to the newly created branch to get your local copy.
In your local copy, open limes.Rproj in RStudio.
Press CTRL+SHIFT+L to call devtools::load_all("."), which loads limes from your local copy.
Assuming you have some mifs available for testing, call

compareScenariosLimes(
  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO.
  outputFile = format(Sys.time(), "CompScen2-%Y%m%d-%H%M%S"),
  sections = NULL,
  envir = globalenv())

This executes the code in cs2_main.Rmd without creating any plots (a mostly empty PDF-file will still be created). This will take some seconds, but it should not take minutes. Type data into the RStudio console and hit enter. This should show you the first rows of a table that contains all the loaded data (ènvir = globalenv() leads render to write all the variables to the environment available in the interactive session (the global environment)).

Open the section file in which you want to add the plot. The files are in the folder inst/markdown/compareScenariosLimes/ and have names of the form c2_NN_XXXX.Rmd, where NN is a two digit number and XXXX resembles the section title.
You should be able to execute any chunk in the section Rmd by clicking the play button in its top right corner.
Insert a new chunk by copying an old one or by pressing CTRL+ALT+I.
Add a new plot inside the chunk, e.g., showLinePlots(data, "Your|Variable|Name"). See Plot Functions below.
Run your newly created chunk to see the plot.
Run the following code to see your new plot in a PDF.

compareScenariosLimes(
  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO.
  outputFile = format(Sys.time(), "CompScen2-%Y%m%d-%H%M%S"),
  outputFormat = "PDF", # PDF is the default, so you can leave that line out. Or change it to html to get a html-version.
  sections = <NN>) # TODO: Replace <NN> by the number of the section you changed (or by "all" to build the whole compare scenarios file, which will take a while)

Save the file. Commit your changes. In the commit message, you may use the shorthand cs2 to indicate that you made a change to compareScenariosLimes, e.g., cs2: added plot of My|Variable.
Make sure you fetched and pulled all recent changes to limes. Then, call lucode2::buildLibrary(). Commit again with the commit message `lucode2::buildLibrary()`. Push your commits to github.
Create a pull request.

cs2_main.Rmd

This file loads the data from the mif-files, preprocesses the data, and includes the section-Rmd-files at the very end (and optionally further Rmd-files provided by the user, see YAML-parameter userSectionPath).

YAML-header

The file cs2_main.Rmd starts with a YAML header marked by ---. This header declares some basic information of the report, like its title and the output format. Furthermore, it contains a list params, which parameterizes the report. Among others, such parameters are the paths to the mif-files and certain properties that are shared for all plots in the report. Each such parameter can be changed by a respective argument in the call of compareScenariosLimes(), see section YAML Parameters in the documentation of the function.

Loading

The mif-files are loaded using quitte::read.quitte(). This function names the global region "World" (not "GLO" as magclass::read.report()). For each file, we obtain one data-frame with columns model, scenario, region, variable, unit, period, value. During preprocessing the data-frames are concatenated into one quitte object named data. In the sections, data is used to provide the data necessary for the plots.

If provided, also config files are loaded.

Preprocessing

Scenarios are renamed if the user specifies new names (using a named vector for the argument mifScen of compareScenariosLimes() or by setting the parameter mifScenNames in the Rmd-files) or if scenario names are duplicate.
The columns period (years) and region are filtered according to the parameters yearsScen, yearsHist, and reg.

Global Variables

Global variables are created in cs2_main.Rmd and are intended to be used in the plot functions of the section-Rmd-files.

The quitte-object (data frame) data with columns model, scenario, region, variable, unit, period, value, varplus provides all data that may be plotted. It has mostly factor-columns. Thus, a vector of all available regions can be obtained by levels(data$region).

Some arguments of the mip::show...() plot functions use the functionality provided by the base-R functions options() and getOption(). In cs2_main.Rmd there are calls to options(), setting values of the global options mip.mainReg, mip.yearsBarPlot, and mip.histRefModel. The plotting functions may have an argument, e.g., mainReg with default value getOption("mip.mainReg"). Thus, this argument does not have to be stated for each call of the plot function (assuming the respective call of options() sets it to the right value).

Section-Rmd-files

The section-Rmd-files follow the naming pattern cs2_NN_XXXX.Rmd, where NN is replaced by a two digit number and XXXX is replaced by a short name of the section. If the YAML-parameter sections is set to "all", the default, all sections of this naming pattern are included in cs2_main.Rmd. Alternatively, sections can be set to a vector of individual sections in the form of "NN_XXXX" to only render these sections.

The section-Rmd-files consist of section and sub-section titles, marked by #, ##, ###, …, and R-code chunks which create plots, usually by calling one of the show...()-functions in the mip package.

userSectionPath

The user can provide one or more additional Rmd-files that are appended after the sections provided by the package. Setting sections to NULL and userSectionPath to a character-vector of paths to Rmd-files creates a fully user-defined report.

Special Sections

There is a first section (section number 0) and a last section in the files cs2_00_info.Rmd and cs2_99_further_info.Rmd, respectively.

0 Info

This section contains a file reference table with scenario names and the paths to the respective mif files. It also show if a scenario is renamed. Renaming can be forced by the user by using a named character vector as argument mifScen where the names indicate the new scenario name, e.g.,

compareScenariosLimes(
  mifScen = c(newName1 = "path/to/scen1.mif", newName2 = "path/to/scen2.mif"),
  ...)

Or, if two scenarios have the same name, they are renamed automatically.

Furthermore, this section displays a description of each scenario. This requires the YAML-parameter cfgScen to be set (see also 99 Further Info). The description can be set in the secenario_config*.csv-file via a column description.

99 Further Info

If compareScenariosLimes() is provided with paths to the config.Rdata files of the scenarios via the YAML-parameter cfgScen and the path to default.cfg via cfgDefault an analysis of the configurations of the scenarios is shown.

compareScenariosLimes(
  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"),
  cfgScen = c("path/to/scen1/config.yml", "path/to/scen2/config.yml"),
  cfgDefault = "path/to/default.cfg",
  ...)

Plot Functions

The section Rmd-files mostly consists of simple calls of a show...()-function from the the mip package. These functions are designed to make the creation of re-occurring kinds of plots in comapreSceanrios2 simple. Alternatively, one can build custom plots using ggplot2.

The mip-package contains following default plot functions for comapareScenarios2:

showAreaAndBarPlots()
showAreaAndBarPlotsPlus()
showLinePlots()
showLinePlotsWithTarget()
showMultiLinePlots
showMultiLinePlotsByVariable()
showRegiLinePlots()

All but showLinePlotsWithTarget() can use the global option mip.mainReg. showAreaAndBarPlots() and showAreaAndBarPlotsPlus() can use mip.yearsBarPlot. showMultiLinePlotsByVariable() uses mip.histRefModel.

See the respective function documentation for more information and example plots.