This tutorial explains how to visually compare the results of multiple runs of the IAM REMIND using the framework piamPlotComparison.
The common use case is creating plots after your REMIND runs have
finished, using the remind/output.R
script: Execute Rscript output.R
in the REMIND folder,
select Comparison across runs
and then
compareScenarios2
.
The function reads the results from the output-mif-files (in the
remind folder after runs are completed, i.e., the files
./output/<run_folder>/REMIND_generic_<run>.mif
).
Additionally it reads historical data from a historical.mif
in one of the run output folders. Using this data, a document containing
many plots is created and written as a PDF- or HTML-file.
The underlying framework used can be found in the R library piamPlotComparison.
The sections of the resulting pdf file are rendered Rmarkdown-files
(Rmd-files). Rmd-files may contain R-code (e.g., for creating plots,
creating tables) as well as descriptive text (in this case, mostly
section titles). The Rmd-files to be rendered are part of the
remind2
-package. In the development state of the package,
the main Rmd-files can be found in the folder remind2/inst/compareScenarios/
.
Some optional section may be placed in the REMIND repository at remind/scripts/cs2/
.
Typically, we want to compare the results of some REMIND runs which
were created in the remind/output/
folder of a clone of the
REMIND repository. Assume such runs are available and, in particular,
the
remind/output/<run_folder>/REMIND_generic_<run>.mif
of the runs of interest exist. Go to the REMIND directory
remind/
and call Rscript output.R
. Then choose
Comparison across runs
and compareScenarios2
.
Select the runs of interest. We then can choose a filename prefix for
the output file if we want. Next, choose a slurm mode, e.g.,
short
(the job will run for less than 1 hour, usually
something like 20min). Finally we can choose a cs2-profile. Standard
profiles for the selected runs are colored. After choosing one or more
profiles, the respective slurm jobs will be started. An HTML- or
PDF-file will be created. If something goes wrong, take a look at the
*.log
-file with the same name as the cs2-output file.
A simple direct call of
piamPlotComparison::compareScenarios()
may look like
this:
library(piamPlotComparison)
compareScenarios(
projectLibrary = "remind2",
mifScen = c("path/to/Base.mif", "path/to/NDC.mif"),
mifHist = "path/to/historical.mif",
outputFile = "CompareScenariosExample")
For further examples and a description of further optional arguments
to the function, see
?piamPlotComparison::compareScenarios
.
It is possible to use paths to the cluster if called at PIK in the
local network (e.g., /p/tmp/username/...
) or in VPN (e.g.,
//clusterfs.pik-potsdam.de/tmp/username/...
).
In this section, we want to execute individual R-code chunks in the cs-Rmd-files interactively in RStudio.
First we need access to the Rmd-files. Here we essentially have two options.
We call piamPlotComparison::compareScenarios()
with
outputFormat = "Rmd"
to obtain a (modified) copy of the
Rmd-files.
library(piamPlotComparison)
compareScenarios(
projectLibrary = "remind2",
mifScen = c("path/to/scen1.mif", "path/to/scen2.mif", "path/to/scen3.mif"), # TODO.
mifHist = "path/to/historical.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
cs_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 we 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.
Clone the remind2
repository. Open a section-Rmd-file cs_NN_XXXX.Rmd
in
RStudio.
Now we want to load the data
object so that the
code-chunks can be executed. If we have VPN or are in the local network
at PIK, we can load the data from the latest automated model tests (AMT)
via remind2::loadModeltest()
. If this is not possible or we
want other mifs to be loaded, we can use
remind2::loadCs2Data()
to create the data
object. See the help pages (?<funName>
) of these
functions for more information. Now the chunks in the Rmd-files should
be executable.
When running compareScenarios
via output script in
REMIND, you are asked to pick one or more cs2-profiles to run.
A cs2-profile is a set of arguments for
piamPlotComparison::compareScenarios()
. There are different
profiles for a comparison on the 12 main REMIND regions
(H12
, H12-short
), or on the European regions
(EU27
, EU27-short
) for 21-region-runs. The
suffix -short
indicates that only periods up to 2050 are
considered. The default
-profiles just call
compareScenarios()
with the default arguments as described
in ?piamPlotComparison::compareScenarios
.
The available profiles are stored in remind/scripts/cs2/profiles.json
.
Take a look at this file (open in text editor) to see the definition of
each profile.
To change a profile or add a new profile, just edit remind/scripts/cs2/profiles.json
.
Read the _DESCRIPTION_
in that file. Every argument
(including YAML-arguments) to compareScenarios()
can be set
or changed.
We can create our own cs2-report: First we create an
“section”-Rmd-file, similar to cs_NN_XXXX.Rmd
in remind2/inst/compareScenarios
.
It typically contains calls to plot-function using an R-object called
data
. This object stores all the information read from the
mif-files. We place our “section”-Rmd-file in remind/scripts/cs2/
.
Then we add a new profile in remind/scripts/cs2/profiles.json
with options "sections": "0"
and
"userSectionPath": "normalizePath('./scripts/cs2/ourSection.Rmd')"
.
The new profile should appear as a choice in the
output.R
-dialog. Choosing it will create a cs2-report
consisting only of the Info-section and our own section. See the profile
mySection
and remind/scripts/cs2/mySection.Rmd
for an example.
The variables in the reported mif-files
(remind/output/<run_folder>/REMIND_generic_<run>.mif
)
have a hierarchical structure induced by the character |
.
This structure can be viewed in a hierarchical list.
In a remind folder with finished runs (with mif-files):
Rscript output.R
Comparison across runs
varListHtml
Then the creation of the a HTML-file containing the hierarchical list of variables names in the chosen mif files is started. Note that it does not use slurm at the moment.
See ?remind2::variablesAsList
.
If connected to the PIK network (possibly via VPN) execute the following code to get an overview of the variables available in the automated model test mifs.
library(remind2)
loadModeltest()
varList <- variablesAsList(data, entry = "INFO")
View(varList) # in RStudio
See also ?createVarListHtml
to create an HTML-file
containing this info.
remind2.Rproj
in RStudio.CTRL+SHIFT+L
to call
devtools::load_all(".")
, which loads remind2
from your local copy.loadModeltest(folder = "some/folder")
. Otherwise call an
adapted form ofThis might take some time (up to 1min). After this, an R-object
data
should be available. Test this by typing
data
into the RStudio Console. The first rows of a
tibble containing some REMIND data should appear. If a bunch of
R-code appears, something went wrong.
inst/compareScenarios/
and have
names of the form cs_NN_XXXX.Rmd
, where NN
is
a two digit number and XXXX
resembles the section
title.CTRL+ALT+I
. Note: It is better to not assign names to the
chunks as cs2 will crash if you used the same name twice.showLinePlots(data, "Your|Variable|Name")
. See [Plot
Functions] below.loadModeltest()
in 6., mif-files should be available in
some/folder/
.compareScenarios(
projectLibrary = "remind2",
mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO.
mifHist = "path/to/historical.mif", # TODO.
outputFile = format(Sys.time(), "cs2-%Y%m%d-%H%M%S"),
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).
cs2
to indicate that you made a change to
compareScenarios, e.g.,
cs2: added plot of My|Variable
.lucode2::buildLibrary()
to check the code and increase the
version number of the package. Commit again with the commit message
`lucode2::buildLibrary()`
. Push your commits to
github.master
branch of the pik-piam/remind2
repository.Most of the general setup for rendering the markdown files is done as
part of the piamPlotComparison
framework in cs_main.Rmd.
Please refer to the vignette
in piamPlotComparison for info on general data preparation steps,
such as renaming scenarios, filtering regions and years, unifying
variable names, setting global variables, etc.
Any additional remind2
-specific code to be executed as
part of the general setup can be found in
inst/compareScenarios/preprocessing.R
.
This includes some data manipulation steps, such as:
mip.histRefModel
that is used
by the mip plotting function
showMultiLinePlotsByVariable
."<OLD_NAME> pCap"
."<OLD_NAME> pGDP"
. As the denominator,
the value of GDP|PPP pCap
is used.Custom code will be executed after the general code.
For more detailed information on the underlying framework, please refer to the vignette in piamPlotComparison.