From 3337a969167fd2b28d928b0e58c404f605dcf275 Mon Sep 17 00:00:00 2001 From: Falk Benke Date: Fri, 26 Apr 2024 16:44:28 +0200 Subject: [PATCH 1/4] update vignette --- .buildlibrary | 2 +- .pre-commit-config.yaml | 4 +- CITATION.cff | 4 +- DESCRIPTION | 4 +- README.md | 6 +- inst/compareScenarios/cs_main.Rmd | 3 +- vignettes/compareScenarios.R | 52 +--- vignettes/compareScenarios.Rmd | 200 ++----------- vignettes/compareScenarios.html | 451 ++++++------------------------ 9 files changed, 135 insertions(+), 591 deletions(-) diff --git a/.buildlibrary b/.buildlibrary index 4743d23..163f9aa 100644 --- a/.buildlibrary +++ b/.buildlibrary @@ -1,4 +1,4 @@ -ValidationKey: '218218' +ValidationKey: '238068' AutocreateReadme: yes AcceptedWarnings: - 'Warning: package ''.*'' was built under R version' diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 243f46a..62f13da 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ exclude: '^tests/testthat/_snaps/.*$' repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: 2c9f875913ee60ca25ce70243dc24d5b6415598c # frozen: v4.6.0 hooks: - id: check-case-conflict - id: check-json @@ -15,7 +15,7 @@ repos: - id: mixed-line-ending - repo: https://github.com/lorenzwalthert/precommit - rev: v0.4.0 + rev: 7910e0323d7213f34275a7a562b9ef0fde8ce1b9 # frozen: v0.4.2 hooks: - id: parsable-R - id: deps-in-desc diff --git a/CITATION.cff b/CITATION.cff index 36069ef..f3a9b56 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,8 +2,8 @@ cff-version: 1.2.0 message: If you use this software, please cite it using the metadata from this file. type: software title: 'piamPlotComparison: Create comparison plots for your model results' -version: 0.0.11 -date-released: '2024-04-25' +version: 0.0.12 +date-released: '2024-04-26' abstract: A frameworks to create comparison plots for your model results. authors: - family-names: Benke diff --git a/DESCRIPTION b/DESCRIPTION index e5374fd..cfe539a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Type: Package Package: piamPlotComparison Title: Create comparison plots for your model results -Version: 0.0.11 -Date: 2024-04-25 +Version: 0.0.12 +Date: 2024-04-26 Authors@R: c( person("Falk", "Benke", , "benke@pik-potsdam.de", role = c("aut", "cre")), person("Christof", "Schoetz", role = "aut") diff --git a/README.md b/README.md index be60522..7e24df7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Create comparison plots for your model results -R package **piamPlotComparison**, version **0.0.11** +R package **piamPlotComparison**, version **0.0.12** [![CRAN status](https://www.r-pkg.org/badges/version/piamPlotComparison)](https://cran.r-project.org/package=piamPlotComparison) [![R build status](https://github.com/pik-piam/piamPlotComparison/workflows/check/badge.svg)](https://github.com/pik-piam/piamPlotComparison/actions) [![codecov](https://codecov.io/gh/pik-piam/piamPlotComparison/branch/master/graph/badge.svg)](https://app.codecov.io/gh/pik-piam/piamPlotComparison) [![r-universe](https://pik-piam.r-universe.dev/badges/piamPlotComparison)](https://pik-piam.r-universe.dev/builds) @@ -46,7 +46,7 @@ In case of questions / problems please contact Falk Benke To cite package **piamPlotComparison** in publications use: -Benke F, Schoetz C (2024). _piamPlotComparison: Create comparison plots for your model results_. R package version 0.0.11, . +Benke F, Schoetz C (2024). _piamPlotComparison: Create comparison plots for your model results_. R package version 0.0.12, . A BibTeX entry for LaTeX users is @@ -55,7 +55,7 @@ A BibTeX entry for LaTeX users is title = {piamPlotComparison: Create comparison plots for your model results}, author = {Falk Benke and Christof Schoetz}, year = {2024}, - note = {R package version 0.0.11}, + note = {R package version 0.0.12}, url = {https://github.com/pik-piam/piamPlotComparison}, } ``` diff --git a/inst/compareScenarios/cs_main.Rmd b/inst/compareScenarios/cs_main.Rmd index 306adef..08675c1 100644 --- a/inst/compareScenarios/cs_main.Rmd +++ b/inst/compareScenarios/cs_main.Rmd @@ -89,6 +89,7 @@ suppressMessages(library(kableExtra)) library(quitte) library(mip) library(piamutils) +library(piamPlotComparison) ``` @@ -282,7 +283,7 @@ data <- as.quitte(data) ```{r remove objects not to be used anymore} varNames <- c( - "availableSections", "cfgTopLevel", "dataScenNested", "env", "envToolsRstudio", + "availableSections", "dataScenNested", "env", "envToolsRstudio", "fn", "insertExprAtStartOfFun", "lightenColor", "loadCfg", "matches", "oldRsSetNotebookGraphicsOption") for (vn in varNames) if (exists(vn)) rm(list = vn) diff --git a/vignettes/compareScenarios.R b/vignettes/compareScenarios.R index feac93b..3132cc0 100644 --- a/vignettes/compareScenarios.R +++ b/vignettes/compareScenarios.R @@ -1,58 +1,20 @@ -## ----include = FALSE--------------------------------------------------------------------------------------------------------------- +## ----include = FALSE------------------------------------------------------------------------------------------------------------------ knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE ) -## ---------------------------------------------------------------------------------------------------------------------------------- -# library(remind2) -# compareScenarios2( -# mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), -# mifHist = "path/to/historical.mif", -# outputFile = "CompareScenarios2Example") - -## ---------------------------------------------------------------------------------------------------------------------------------- -# library(remind2) -# compareScenarios2( -# 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")) - -## ----prepare mark------------------------------------------------------------------------------------------------------------------ -# # CLICK "RUN ALL CHUNKS ABOVE" HERE TO PREPARE THE ENVIRONMENT - -## ---------------------------------------------------------------------------------------------------------------------------------- -# library(remind2) -# loadModeltest() -# varList <- variablesAsList(data, entry = "INFO") -# View(varList) # in RStudio - -## ---------------------------------------------------------------------------------------------------------------------------------- -# loadCs2Data( -# c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO. -# "path/to/historical.mif") # TODO. - -## ---------------------------------------------------------------------------------------------------------------------------------- -# compareScenarios2( -# 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). - -## ---------------------------------------------------------------------------------------------------------------------------------- -# compareScenarios2( +## ------------------------------------------------------------------------------------------------------------------------------------- +# compareScenarios( +# projectLibrary = "myProjectLib", # mifScen = c(newName1 = "path/to/scen1.mif", newName2 = "path/to/scen2.mif"), # ...) -## ---------------------------------------------------------------------------------------------------------------------------------- -# compareScenarios2( +## ------------------------------------------------------------------------------------------------------------------------------------- +# compareScenarios( +# projectLibrary = "myProjectLib", # mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), # cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"), -# cfgDefault = "path/to/default.cfg", # ...) diff --git a/vignettes/compareScenarios.Rmd b/vignettes/compareScenarios.Rmd index ebf8b06..e7edf98 100644 --- a/vignettes/compareScenarios.Rmd +++ b/vignettes/compareScenarios.Rmd @@ -1,7 +1,7 @@ --- title: "compareScenarios" -author: "Christof Schötz" -date: "2024-04-05" +author: "Falk Benke" +date: "2024-04-26" output: rmarkdown::html_vignette: toc: true @@ -22,171 +22,23 @@ knitr::opts_chunk$set( # Overview -The function `compareScenarios()` can be used to visually compare the results of multiple runs of IAMs like [REMIND](https://github.com/remindmodel/remind) or [EDGE-T](https://github.com/pik-piam/edgeTransport). - -It can be called via the [`remind/output.R`](https://github.com/remindmodel/remind/blob/develop/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//REMIND_generic_.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. See `?piamPlotComparison::compareScenarios` for information on how to call the function directly with the appropriate arguments. - -Internally, `compareScenarios()` calls `rmarkdown::render()` on certain 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 main Rmd-files to be rendered are part of the remind2-package. Some optional section may be placed in the REMIND repository at [`remind/scripts/cs2/`](https://github.com/remindmodel/remind/tree/develop/scripts/cs2). In the development state of the package, the main Rmd-files can be found in the folder [`remind2/inst/compareScenarios/`](https://github.com/pik-piam/remind2/tree/master/inst/compareScenarios). -To be more precise, `rmarkdown::render()` is called on `cs_main.Rmd` of [this library](https://github.com/pik-piam/piamPlotComparison/tree/master/inst/compareScenarios), which includes other Rmd-files - one for each section of the output document. +Internally, `compareScenarios()` calls `rmarkdown::render()` on certain Rmarkdown-files (Rmd-files). . +To be more precise, `rmarkdown::render()` is called on [cs_main.Rmd](https://github.com/fbenke-pik/piamPlotComparison/blob/master/inst/compareScenarios/cs_main.Rmd) of the piamPlotComparison package, which includes other Rmd-files - one for each section of the output document. The loading and preprocessing of data happens in `cs_main.Rmd`; the section Rmd-files mostly call plot functions. Aside from HTML- and PDF-documents as output, `compareScenarios()` 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 `compareScenarios()` 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 `remind2`-package. Moreover, Rmd-files can be used interactively in RStudio. # Usage -`compareScenarios()` with different predefined settings can be called via `Rscript output.R`. It can also be called directly as a function of the R-package `piamPlotComparison`. - -## output.R and Profiles - -### output.R - -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//REMIND_generic_.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. - -### Profiles - -A cs2-profile is a set of arguments for `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`](https://github.com/remindmodel/remind/blob/develop/scripts/cs2/profiles.json). Take a look at this file (open in text editor) to see the definition of each profile. - -### Changing or Adding Profiles - -To change a profile or add a new profile, just edit [`remind/scripts/cs2/profiles.json`](https://github.com/remindmodel/remind/blob/develop/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 cs-report: -First, we create an "section"-Rmd-file, similar to `cs2_NN_XXXX.Rmd` in [`remind2/inst/markdown/compareScenarios2`](https://github.com/pik-piam/remind2/tree/master/inst/markdown/compareScenarios2). It typically contains calls to plot-function using an R-object called `data`. This objects stores all the information read from the mif-files. We place our "section"-Rmd-file in [`remind/scripts/cs2/`](https://github.com/remindmodel/remind/tree/develop/scripts/cs2). Then we add a new profile in [`remind/scripts/cs2/profiles.json`](https://github.com/remindmodel/remind/blob/develop/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 consisiting only of the Info-section and our own section. See the profile `mySection` and [`remind/scripts/cs2/mySection.Rmd`](https://github.com/remindmodel/remind/blob/develop/scripts/cs2/mySection.Rmd) for an example. - -## Direct Call and mif-Files - -A simple direct call of `compareScenarios2()` may look like this: - -```{r} -library(remind2) -compareScenarios2( - mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), - mifHist = "path/to/historical.mif", - outputFile = "CompareScenarios2Example") -``` - -For further examples and a description of further optional arguments to the function, see `?remind2::compareScenarios2`. - -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/...`). - - -# Interactive Use of the Rmd-files - - -In this section, we want to execute individual R-code chunks in the cs2-Rmd-files interactively in RStudio. - -First we need access to the Rmd-files. Here we essentially have two options. - -## Using outputFormat = "Rmd" - -We call `remind2::compareScenarios2()` with `outputFormat = "Rmd"` to obtain a (modified) copy of the Rmd-files. - -```{r} -library(remind2) -compareScenarios2( - 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 `cs2_main.Rmd`. At the end of the file, there is a chunk -```` -```{r prepare mark} -# 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. - -## Using a cloned remind2 repository - -Clone the [remind2 repository](https://github.com/pik-piam/remind2). Open a section-Rmd-file `cs2_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 (`?`) of these functions for more information. Now the chunks in the Rmd-files should be executable. +... - -# Viewing Available Variables in mif Files - -The variables in the reported mif-files (`remind/output//REMIND_generic_.mif`) have a hierarchical structure induced by the character `|`. This structure can be viewed in a hierarchical list. - -## output.R - -In a remind folder with finished runs (with mif-files): - -1. execute `Rscript output.R` -2. choose `Comparison across runs` -3. choose `varListHtml` -4. choose the runs you want to read the mif files from -5. choose a file name prefix if you like - -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. - -## Package Function - -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. - -```{r} -library(remind2) -loadModeltest() -varList <- variablesAsList(data, entry = "INFO") -View(varList) # in RStudio -``` - -See also `?createVarListHtml` to create an HTML-file containing this info. - - - -# Workflow for Adding a New Plot to CompareScenarios2 - -1. If not done already, fork . -2. In your personal github remind2 repository, create a new branch. -3. Clone the repository and switch to the newly created branch to get your local copy. -4. In your local copy, open `remind2.Rproj` in RStudio. -5. Press `CTRL+SHIFT+L` to call `devtools::load_all(".")`, which loads `remind2` from your local copy. -6. If it is sufficient to test your new plots on the latest AMTs and you are connected to the PIK network (possibly via VPN), call `loadModeltest(folder = "some/folder")`. Otherwise call an adapted form of - -```{r} -loadCs2Data( - c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO. - "path/to/historical.mif") # TODO. -``` - -This 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. - -7. Open the section-Rmd-file in which you want to add the plot. The files are in the folder `inst/markdown/compareScenarios2/` and have names of the form `cs2_NN_XXXX.Rmd`, where `NN` is a two digit number and `XXXX` resembles the section title. -8. You should be able to execute any chunk in the section Rmd by clicking the play button in its top right corner. -9. Insert a new chunk by copying an old one or by pressing `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. -10. Add a new plot inside the chunk, e.g., `showLinePlots(data, "Your|Variable|Name")`. See [Plot Functions] below. -11. Run your newly created chunk to see the plot. -12. Run the following code to see your new plot in a PDF. If you used `loadModeltest()` in 6., mif-files should be available in `some/folder/`. - -```{r} -compareScenarios2( - 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). -``` - -13. Commit your changes. In the commit message, you may use the shorthand `cs2` to indicate that you made a change to compareScenarios2, e.g., `cs2: added plot of My|Variable`. -14. Make sure you pulled all recent changes to remind2. Then, call `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. -15. Create a pull request of your branch to the `master` branch of the `pik-piam/remind2` repository. - -# cs2_main.Rmd +# cs_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 `compareScenarios2()`, see section *YAML Parameters* in the documentation of the function. +The file `cs_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 `compareScenarios()`, see section *YAML Parameters* in the documentation of the function. ## Loading @@ -196,24 +48,26 @@ 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 `compareScenarios2()` or by setting the parameter `mifScenNames` in the Rmd-files) or if scenario names are duplicate. +* Scenarios are renamed if the user specifies new names (using a named vector for the argument `mifScen` of `compareScenarios()` 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`. -* `|+|, |++|, |+++|, ...` are removed from variable names. See also `remind2::deletePlus`. An additional column `varplus` is added to the data frame, which retains the original name including `+`. This column is used by `mip::showAreaAndBarPlotsPlus()`. -* For a specified list of variables, a new per-capita-variable is created with the name `" pCap"`. -* For a specified list of variables, a new per-GDP-variable is created with the name `" pGDP"`. As the denominator, the value of `GDP|PPP pCap` is used. +* `|+|, |++|, |+++|, ...` are removed from variable names. See also `piamutils::deletePlus`. An additional column `varplus` is added to the data frame, which retains the original name including `+`. This column is used by `mip::showAreaAndBarPlotsPlus()`. + +If you need to execute any additional code as part of the general setup, put it into a file `inst/compareScenarios/preprocessing.R` in the project library. Custom code will be executed after the general code. ## 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. +Global variables are created in `cs_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). +Some arguments of the `mip::show...()` plot functions use the functionality provided by the base-R functions `options()` and `getOption()`. In `cs_main.Rmd` there are calls to `options()`, setting values of the global options `mip.mainReg` and `mip.yearsBarPlot`. 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). + +If you want to set `mip.histRefModel`, please do so in the `preprocessing.R` file of your project library. # 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 follow the naming pattern `cs_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 by `cs_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. @@ -223,43 +77,42 @@ The user can provide one or more additional Rmd-files that are appended after th ## 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. +There is a first section (section number 0) and a last section in the files `cs_00_info.Rmd` and `cs_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., ```{r} -compareScenarios2( +compareScenarios( + projectLibrary = "myProjectLib", 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`. - +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 `scenario_config*.csv`-file via a column `description`. ### 99 Further Info {-} -If `compareScenarios2()` is provided with paths to the `config.Rdata` files of the scenarios via the YAML-parameter `cfgScen` and the path to `default.cfg` ([this](https://github.com/remindmodel/remind/tree/develop/config/default.cfg) file) via `cfgDefault` an analysis of the configurations of the scenarios is shown. +If `compareScenarios()` is provided with paths to the `config.Rdata` files of the scenarios via the YAML-parameter `cfgScen`, an analysis of the configurations of the scenarios is shown. ```{r} -compareScenarios2( +compareScenarios( + projectLibrary = "myProjectLib", mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"), - cfgDefault = "path/to/default.cfg", ...) ``` - # Content Functions ## Plot Functions -The section Rmd-files mostly consist of simple calls of a `show...()`-function from the the [mip](https://github.com/pik-piam/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 section Rmd-files mostly consist of simple calls of a `show...()`-function from the the [mip](https://github.com/pik-piam/mip) package. These functions are designed to make the creation of re-occurring kinds of plots in `comapreSceanrios` simple. Alternatively, one can build custom plots using `ggplot2`. -The `mip`-package contains following default plot functions for comapareScenarios2: +The `mip`-package contains following default plot functions for `comapareScenarios`: * `showAreaAndBarPlots()` * `showAreaAndBarPlotsPlus()` @@ -277,4 +130,5 @@ See the respective function documentation for more information and example plots ## Table Functions -For creating tables in cs2, see the documentation of `remind2::calcTimeSeriesStats()` and `remind2::showStatsTable()` and -- for an example -- the section **Tables of Significant Periods** in [`remind2/inst/markdown/compareScenarios2/cs2_01_summary.Rmd`](https://github.com/pik-piam/remind2/blob/master/inst/markdown/compareScenarios2/cs2_01_summary.Rmd). +For creating tables in cs, see the documentation of `piamPlotComparison::calcTimeSeriesStats()` and `piamPlotComparison::showStatsTable()` and -- for an example -- the section **Tables of Significant Periods** in [`remind2/inst/compareScenarios/cs2_01_summary.Rmd`](https://github.com/pik-piam/remind2/blob/master/inst/compareScenarios/cs_01_summary.Rmd). + diff --git a/vignettes/compareScenarios.html b/vignettes/compareScenarios.html index cd345a3..9a1c9e0 100644 --- a/vignettes/compareScenarios.html +++ b/vignettes/compareScenarios.html @@ -10,9 +10,9 @@ - + - + compareScenarios @@ -339,94 +339,49 @@

compareScenarios

-

Christof Schötz

-

2024-04-05

+

Falk Benke

+

2024-04-26

1 Overview

-

The function compareScenarios() can be used to visually -compare the results of multiple runs of IAMs like REMIND or EDGE-T.

-

It can be called via 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. See -?piamPlotComparison::compareScenarios for information on -how to call the function directly with the appropriate arguments.

Internally, compareScenarios() calls rmarkdown::render() on certain 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 -main Rmd-files to be rendered are part of the remind2-package. Some -optional section may be placed in the REMIND repository at remind/scripts/cs2/. -In the development state of the package, the main Rmd-files can be found -in the folder remind2/inst/compareScenarios/. -To be more precise, rmarkdown::render() is called on -cs_main.Rmd of this -library, which includes other Rmd-files - one for each section of -the output document. The loading and preprocessing of data happens in -cs_main.Rmd; the section Rmd-files mostly call plot -functions.

+.
+To be more precise, rmarkdown::render() is called on cs_main.Rmd +of the piamPlotComparison package, which includes other Rmd-files - one +for each section of the output document. The loading and preprocessing +of data happens in cs_main.Rmd; the section Rmd-files +mostly call plot functions.

Aside from HTML- and PDF-documents as output, compareScenarios() also allows to obtain a copy of the Rmd-files needed to create these outputs (by setting the argument @@ -440,256 +395,28 @@

1 Overview

2 Usage

-

compareScenarios() with different predefined settings -can be called via Rscript output.R. It can also be called -directly as a function of the R-package -piamPlotComparison.

-
-

2.1 output.R and -Profiles

-
-

2.1.1 output.R

-

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.

-
-
-

2.1.2 Profiles

-

A cs2-profile is a set of arguments for -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.

-
-
-

2.1.3 Changing or Adding -Profiles

-

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 cs-report: First, we create an -“section”-Rmd-file, similar to cs2_NN_XXXX.Rmd in remind2/inst/markdown/compareScenarios2. -It typically contains calls to plot-function using an R-object called -data. This objects 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 -consisiting only of the Info-section and our own section. See the -profile mySection and remind/scripts/cs2/mySection.Rmd -for an example.

-
-
-
-

2.2 Direct Call and -mif-Files

-

A simple direct call of compareScenarios2() may look -like this:

-
library(remind2)
-compareScenarios2(
-  mifScen = c("path/to/Base.mif", "path/to/NDC.mif"),
-  mifHist = "path/to/historical.mif",
-  outputFile = "CompareScenarios2Example")
-

For further examples and a description of further optional arguments -to the function, see ?remind2::compareScenarios2.

-

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/...).

-
-
-
-

3 Interactive Use of the -Rmd-files

-

In this section, we want to execute individual R-code chunks in the -cs2-Rmd-files interactively in RStudio.

-

First we need access to the Rmd-files. Here we essentially have two -options.

-
-

3.1 Using outputFormat = -“Rmd”

-

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

-
library(remind2)
-compareScenarios2(
-  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 -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 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.

-
-
-

3.2 Using a cloned -remind2 repository

-

Clone the remind2 -repository. Open a section-Rmd-file cs2_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.

-
-
-
-

4 Viewing Available -Variables in mif Files

-

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.

-
-

4.1 output.R

-

In a remind folder with finished runs (with mif-files):

-
    -
  1. execute Rscript output.R
    2. -
  2. choose Comparison across runs
    3. -
  3. choose varListHtml
    4. -
  4. choose the runs you want to read the mif files from
    5. -
  5. choose a file name prefix if you like
    6. -
-

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.

-
-
-

4.2 Package Function

-

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.

-
-
-
-

5 Workflow for Adding a -New Plot to CompareScenarios2

-
    -
  1. If not done already, fork https://github.com/pik-piam/remind2.
    2. -
  2. In your personal github remind2 repository, create a new -branch.
    3. -
  3. Clone the repository and switch to the newly created branch to get -your local copy.
    4. -
  4. In your local copy, open remind2.Rproj in RStudio.
    5. -
  5. Press CTRL+SHIFT+L to call -devtools::load_all("."), which loads remind2 -from your local copy.
    6. -
  6. If it is sufficient to test your new plots on the latest AMTs and -you are connected to the PIK network (possibly via VPN), call -loadModeltest(folder = "some/folder"). Otherwise call an -adapted form of
    7. -
-
loadCs2Data(
-  c("path/to/scen1.mif", "path/to/scen2.mif"), # TODO.
-  "path/to/historical.mif") # TODO.
-

This 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.

-
    -
  1. Open the section-Rmd-file in which you want to add the plot. The -files are in the folder inst/markdown/compareScenarios2/ -and have names of the form cs2_NN_XXXX.Rmd, where -NN is a two digit number and XXXX resembles -the section title.
    2. -
  2. You should be able to execute any chunk in the section Rmd by -clicking the play button in its top right corner.
    3. -
  3. Insert a new chunk by copying an old one or by pressing -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.
    4. -
  4. Add a new plot inside the chunk, e.g., -showLinePlots(data, "Your|Variable|Name"). See Plot Functions below.
    5. -
  5. Run your newly created chunk to see the plot.
    6. -
  6. Run the following code to see your new plot in a PDF. If you used -loadModeltest() in 6., mif-files should be available in -some/folder/.
    7. -
-
compareScenarios2(
-  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).
-
    -
  1. Commit your changes. In the commit message, you may use the -shorthand cs2 to indicate that you made a change to -compareScenarios2, e.g., -cs2: added plot of My|Variable.
    2. -
  2. Make sure you pulled all recent changes to remind2. Then, call -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.
    3. -
  3. Create a pull request of your branch to the master -branch of the pik-piam/remind2 repository.
    4. -
+

…

-
-

6 cs2_main.Rmd

+
+

3 cs_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).

-
-

6.1 YAML-header

-

The file cs2_main.Rmd starts with a YAML header marked -by ---. This header declares some basic information of the +

+

3.1 YAML-header

+

The file cs_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 -compareScenarios2(), see section YAML Parameters -in the documentation of the function.

+compareScenarios(), see section YAML Parameters in +the documentation of the function.

-
-

6.2 Loading

+
+

3.2 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 @@ -700,32 +427,31 @@

6.2 Loading

used to provide the data necessary for the plots.

If provided, also config files are loaded.

-
-

6.3 Preprocessing

+
+

3.3 Preprocessing

  • Scenarios are renamed if the user specifies new names (using a named vector for the argument mifScen of -compareScenarios2() or by setting the parameter +compareScenarios() 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.
  • |+|, |++|, |+++|, ... are removed from variable names. -See also remind2::deletePlus. An additional column +See also piamutils::deletePlus. An additional column varplus is added to the data frame, which retains the original name including +. This column is used by mip::showAreaAndBarPlotsPlus().
    • -
  • For a specified list of variables, a new per-capita-variable is -created with the name "<OLD_NAME> pCap".
    • -
  • For a specified list of variables, a new per-GDP-variable is created -with the name "<OLD_NAME> pGDP". As the denominator, -the value of GDP|PPP pCap is used.
+

If you need to execute any additional code as part of the general +setup, put it into a file +inst/compareScenarios/preprocessing.R in the project +library. Custom code will be executed after the general code.

-
-

6.4 Global Variables

-

Global variables are created in cs2_main.Rmd and are +

+

3.4 Global Variables

+

Global variables are created in cs_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 @@ -735,43 +461,44 @@

6.4 Global Variables

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).

+cs_main.Rmd there are calls to options(), +setting values of the global options mip.mainReg and +mip.yearsBarPlot. 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).

+

If you want to set mip.histRefModel, please do so in the +preprocessing.R file of your project library.

-
-

7 Section-Rmd-files

+
+

4 Section-Rmd-files

The section-Rmd-files follow the naming pattern -cs2_NN_XXXX.Rmd, where NN is replaced by a two +cs_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, +included by cs_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.

-
-

7.1 userSectionPath

+
+

4.1 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.

-
-

7.2 Special Sections

+
+

4.2 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.

+files cs_00_info.Rmd and +cs_99_further_info.Rmd, respectively.

0 Info

This section contains a file reference table with scenario names and @@ -779,43 +506,43 @@

0 Info

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.,

-
compareScenarios2(
-  mifScen = c(newName1 = "path/to/scen1.mif", newName2 = "path/to/scen2.mif"),
-  ...)
+
compareScenarios(
+  projectLibrary = "myProjectLib",
+  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 +be set in the scenario_config*.csv-file via a column description.

99 Further Info

-

If compareScenarios2() is provided with paths to the +

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

-
compareScenarios2(
-  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"),
-  cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"),
-  cfgDefault = "path/to/default.cfg",
-  ...)
+cfgScen, an analysis of the configurations of the scenarios +is shown.

+
compareScenarios(
+  projectLibrary = "myProjectLib",
+  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"),
+  cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"),
+  ...)
-
-

8 Content Functions

-
-

8.1 Plot Functions

+
+

5 Content Functions

+
+

5.1 Plot Functions

The section Rmd-files mostly consist 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.

+comapreSceanrios simple. Alternatively, one can build +custom plots using ggplot2.

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

+functions for comapareScenarios:

  • showAreaAndBarPlots()
  • showAreaAndBarPlotsPlus()
    • @@ -834,12 +561,12 @@

    8.1 Plot Functions

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

-
-

8.2 Table Functions

-

For creating tables in cs2, see the documentation of -remind2::calcTimeSeriesStats() and -remind2::showStatsTable() and – for an example – the -section Tables of Significant Periods in remind2/inst/markdown/compareScenarios2/cs2_01_summary.Rmd.

+
+

5.2 Table Functions

+

For creating tables in cs, see the documentation of +piamPlotComparison::calcTimeSeriesStats() and +piamPlotComparison::showStatsTable() and – for an example – +the section Tables of Significant Periods in remind2/inst/compareScenarios/cs2_01_summary.Rmd.

From 9ca1c7f9fd831d9858673b0e1aeb66b0fedd61e1 Mon Sep 17 00:00:00 2001 From: Falk Benke Date: Fri, 26 Apr 2024 18:24:32 +0200 Subject: [PATCH 2/4] update documentation of compareScenarios --- R/compareScenarios.R | 14 +++++++----- man/compareScenarios.Rd | 21 ++++++++++-------- vignettes/compareScenarios.Rmd | 12 +++++----- vignettes/compareScenarios.html | 39 ++++++++++++++++++--------------- 4 files changed, 48 insertions(+), 38 deletions(-) diff --git a/R/compareScenarios.R b/R/compareScenarios.R index e8e8da7..41df38d 100644 --- a/R/compareScenarios.R +++ b/R/compareScenarios.R @@ -6,10 +6,10 @@ #' choose Rmd as output format and obtain a copy of the *.Rmd-files. #' #' @param projectLibrary \code{NULL} or \code{character(n)}. Default: \code{NULL}. -#' An R library containing Rmd files that could be included. You can further filter -#' the sections to be rendered using the \code{sections} YAML parameter. -#' Expects the Rmd files must be placed in a folder \code{inst/compareScenarios}. -#' Files must have the format \code{cs_[NUMBER]_*.Rmd} to be considered. +#' An R reporting library containing Rmd files to be included. +#' You can further filter the sections to be rendered using the \code{sections} YAML parameter. +#' The Rmd files must be placed in a folder \code{inst/compareScenarios}. +#' Files must have the format \code{cs_NN_XXXX.Rmd} to be considered. #' If the folder contains a file \code{preprocessing.Rmd}, it will be executed #' before rendering the sections. #' @param mifScen \code{character(n)}, optionally named. Paths to scenario mifs. @@ -95,11 +95,13 @@ #' \dontrun{ #' # Simple use. Creates PDF: #' compareScenarios( +#' projectLibrary = "mylib", #' mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), #' mifHist = "path/to/historical.mif", #' outputFile = "CompareScenariosExample") #' # More complex use. Creates folder with Rmds: #' compareScenarios( +#' projectLibrary = "mylib", #' mifScen = c(ScenarioName1 = "path/to/scen1.mif", ScenarioName2 = "path/to/scen2.mif"), #' mifHist = "path/to/historical.mif", #' cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"), @@ -111,6 +113,7 @@ #' userSectionPath = "path/to/myPlots.Rmd") #' # Use in development. Load data into global environment: #' compareScenarios( +#' projectLibrary = "mylib", #' mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), #' mifHist = "path/to/historical.mif", #' outputFile = format(Sys.time(), "cs2_load_%Y%m%d-%H%M%S"), @@ -119,8 +122,9 @@ #' } #' @export compareScenarios <- function( - mifScen, mifHist, projectLibrary = NULL, + mifScen, + mifHist, outputDir = getwd(), outputFile = "CompareScenarios", outputFormat = "PDF", diff --git a/man/compareScenarios.Rd b/man/compareScenarios.Rd index eedd7b0..1241c28 100644 --- a/man/compareScenarios.Rd +++ b/man/compareScenarios.Rd @@ -5,9 +5,9 @@ \title{Render CompareScenarios} \usage{ compareScenarios( + projectLibrary = NULL, mifScen, mifHist, - projectLibrary = NULL, outputDir = getwd(), outputFile = "CompareScenarios", outputFormat = "PDF", @@ -17,20 +17,20 @@ compareScenarios( ) } \arguments{ +\item{projectLibrary}{\code{NULL} or \code{character(n)}. Default: \code{NULL}. +An R reporting library containing Rmd files to be included. +You can further filter the sections to be rendered using the \code{sections} YAML parameter. +The Rmd files must be placed in a folder \code{inst/compareScenarios}. +Files must have the format \code{cs_NN_XXXX.Rmd} to be considered. +If the folder contains a file \code{preprocessing.Rmd}, it will be executed +before rendering the sections.} + \item{mifScen}{\code{character(n)}, optionally named. Paths to scenario mifs. If the vector has names, those are used to refer to the scenarios in the output file.} \item{mifHist}{\code{character(1)}. Path to historical mif.} -\item{projectLibrary}{\code{NULL} or \code{character(n)}. Default: \code{NULL}. -An R library containing Rmd files that could be included. You can further filter -the sections to be rendered using the \code{sections} YAML parameter. -Expects the Rmd files must be placed in a folder \code{inst/compareScenarios}. -Files must have the format \code{cs_[NUMBER]_*.Rmd} to be considered. -If the folder contains a file \code{preprocessing.Rmd}, it will be executed -before rendering the sections.} - \item{outputDir}{\code{character(1)}. The directory where the output document and intermediary files are created.} @@ -125,11 +125,13 @@ choose Rmd as output format and obtain a copy of the *.Rmd-files. \dontrun{ # Simple use. Creates PDF: compareScenarios( + projectLibrary = "mylib", mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), mifHist = "path/to/historical.mif", outputFile = "CompareScenariosExample") # More complex use. Creates folder with Rmds: compareScenarios( + projectLibrary = "mylib", mifScen = c(ScenarioName1 = "path/to/scen1.mif", ScenarioName2 = "path/to/scen2.mif"), mifHist = "path/to/historical.mif", cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"), @@ -141,6 +143,7 @@ compareScenarios( userSectionPath = "path/to/myPlots.Rmd") # Use in development. Load data into global environment: compareScenarios( + projectLibrary = "mylib", mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"), mifHist = "path/to/historical.mif", outputFile = format(Sys.time(), "cs2_load_\%Y\%m\%d-\%H\%M\%S"), diff --git a/vignettes/compareScenarios.Rmd b/vignettes/compareScenarios.Rmd index e7edf98..e3ec51a 100644 --- a/vignettes/compareScenarios.Rmd +++ b/vignettes/compareScenarios.Rmd @@ -22,19 +22,19 @@ knitr::opts_chunk$set( # Overview -Internally, `compareScenarios()` calls `rmarkdown::render()` on certain Rmarkdown-files (Rmd-files). . -To be more precise, `rmarkdown::render()` is called on [cs_main.Rmd](https://github.com/fbenke-pik/piamPlotComparison/blob/master/inst/compareScenarios/cs_main.Rmd) of the piamPlotComparison package, which includes other Rmd-files - one for each section of the output document. -The loading and preprocessing of data happens in `cs_main.Rmd`; the section Rmd-files mostly call plot functions. +`piamPlotComparison` is a lightweight framework to visually compare the results of multiple runs of models, such as [REMIND](https://github.com/remindmodel/remind) or [EDGE-T](https://github.com/pik-piam/edgeTransport). -Aside from HTML- and PDF-documents as output, `compareScenarios()` 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 `compareScenarios()` 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 `remind2`-package. Moreover, Rmd-files can be used interactively in RStudio. +It is used in conjunction with a reporting library, such as [remind2](https://github.com/pik-piam/remind2) or [reporttransport](https://github.com/pik-piam/reporttransport). The reporting library includes Rmarkdown-files (Rmd-files) with R-code (e.g., for creating plots, creating tables) as well as descriptive text following some conventions. The framework offers functionality that reads model runs and produces either HTML- and PDF-documents using the Rmd-files via the core function `compareScenarios`. -# Usage +Aside from HTML- and PDF-documents as output, `compareScenarios` 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 `compareScenarios()` 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 reporting library. Moreover, Rmd-files can be used interactively in RStudio. + +# Minimal setup ... # cs_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`). +Internally, `compareScenarios()` calls `rmarkdown::render()` on certain Rmarkdown-files (Rmd-files). To be more precise, `rmarkdown::render()` is called on [cs_main.Rmd](https://github.com/pik-piam/piamPlotComparison/blob/master/inst/compareScenarios/cs_main.Rmd). This file loads the data from the mif-files, preprocesses the data, and includes the section-Rmd-files from the project library at the very end (and optionally further Rmd-files provided by the user, see YAML-parameter `userSectionPath`). ## YAML-header diff --git a/vignettes/compareScenarios.html b/vignettes/compareScenarios.html index 9a1c9e0..dfe911d 100644 --- a/vignettes/compareScenarios.html +++ b/vignettes/compareScenarios.html @@ -346,7 +346,7 @@

2024-04-26

  • 1 Overview
    • -
  • 2 Usage
    • +
  • 2 Minimal setup
  • 3 cs_main.Rmd
    • 3.1 YAML-header
      • @@ -374,35 +374,38 @@

      2024-04-26

      1 Overview

      -

      Internally, compareScenarios() calls -rmarkdown::render() on certain Rmarkdown-files (Rmd-files). -.
      -To be more precise, rmarkdown::render() is called on cs_main.Rmd -of the piamPlotComparison package, which includes other Rmd-files - one -for each section of the output document. The loading and preprocessing -of data happens in cs_main.Rmd; the section Rmd-files -mostly call plot functions.

      +

      piamPlotComparison is a lightweight framework to +visually compare the results of multiple runs of models, such as REMIND or EDGE-T.

      +

      It is used in conjunction with a reporting library, such as remind2 or reporttransport. +The reporting library includes Rmarkdown-files (Rmd-files) with R-code +(e.g., for creating plots, creating tables) as well as descriptive text +following some conventions. The framework offers functionality that +reads model runs and produces either HTML- and PDF-documents using the +Rmd-files via the core function compareScenarios.

      Aside from HTML- and PDF-documents as output, -compareScenarios() also allows to obtain a copy of the +compareScenarios 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 compareScenarios() 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 remind2-package. Moreover, -Rmd-files can be used interactively in RStudio.

      +changing the code of the reporting library. Moreover, Rmd-files can be +used interactively in RStudio.

      -
      -

      2 Usage

      +
      +

      2 Minimal setup

      …

      3 cs_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).

      +

      Internally, compareScenarios() calls +rmarkdown::render() on certain Rmarkdown-files (Rmd-files). +To be more precise, rmarkdown::render() is called on cs_main.Rmd. +This file loads the data from the mif-files, preprocesses the data, and +includes the section-Rmd-files from the project library at the very end +(and optionally further Rmd-files provided by the user, see +YAML-parameter userSectionPath).

      3.1 YAML-header

      The file cs_main.Rmd starts with a YAML header marked by From 2283ee379d528bbe654563a95422602187da966b Mon Sep 17 00:00:00 2001 From: Falk Benke Date: Fri, 26 Apr 2024 19:04:08 +0200 Subject: [PATCH 3/4] update tutorial --- vignettes/compareScenarios.R | 22 ++++++ vignettes/compareScenarios.Rmd | 57 +++++++++++++++- vignettes/compareScenarios.html | 115 +++++++++++++++++++++++++++----- 3 files changed, 175 insertions(+), 19 deletions(-) diff --git a/vignettes/compareScenarios.R b/vignettes/compareScenarios.R index 3132cc0..5583710 100644 --- a/vignettes/compareScenarios.R +++ b/vignettes/compareScenarios.R @@ -5,6 +5,28 @@ knitr::opts_chunk$set( eval = FALSE ) +## ------------------------------------------------------------------------------------------------------------------------------------- +# library(piamPlotComparison) +# compareScenarios( +# projectLibrary = "myProjectLibrary", +# mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), +# mifHist = "path/to/historical.mif", +# outputFile = "CompareScenariosExample") + +## ------------------------------------------------------------------------------------------------------------------------------------- +# library(piamPlotComparison) +# compareScenarios( +# projectLibrary = "myProjectLib", +# 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")) + +## ----prepare mark--------------------------------------------------------------------------------------------------------------------- +# # CLICK "RUN ALL CHUNKS ABOVE" HERE TO PREPARE THE ENVIRONMENT + ## ------------------------------------------------------------------------------------------------------------------------------------- # compareScenarios( # projectLibrary = "myProjectLib", diff --git a/vignettes/compareScenarios.Rmd b/vignettes/compareScenarios.Rmd index e3ec51a..7fa1e76 100644 --- a/vignettes/compareScenarios.Rmd +++ b/vignettes/compareScenarios.Rmd @@ -26,13 +26,64 @@ knitr::opts_chunk$set( It is used in conjunction with a reporting library, such as [remind2](https://github.com/pik-piam/remind2) or [reporttransport](https://github.com/pik-piam/reporttransport). The reporting library includes Rmarkdown-files (Rmd-files) with R-code (e.g., for creating plots, creating tables) as well as descriptive text following some conventions. The framework offers functionality that reads model runs and produces either HTML- and PDF-documents using the Rmd-files via the core function `compareScenarios`. +Internally, `compareScenarios()` calls `rmarkdown::render()` on [cs_main.Rmd](https://github.com/pik-piam/piamPlotComparison/blob/master/inst/compareScenarios/cs_main.Rmd). This file loads the data from the mif-files, preprocesses the data, and includes the section-Rmd-files from the project library. + Aside from HTML- and PDF-documents as output, `compareScenarios` 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 `compareScenarios()` 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 reporting library. Moreover, Rmd-files can be used interactively in RStudio. -# Minimal setup +# Getting Started + +## Add Rmd files to your reporting library + +Create a folder `inst/compareScenarios` in your reporting library and place one Rmd-file for each section in your document in this folder. The section-Rmd-files follow the naming pattern `cs_NN_XXXX.Rmd`, where `NN` is replaced by a two digit number and `XXXX` is replaced by a short name of the section. + +The Rmd-files usually contain chunks with plots. For plotting, we usually use the [mip](https://github.com/pik-piam/mip) package or `ggplot`. The frameworks provides the `data` object containing your model runs and historical / reference data for plotting. + +The framework takes care of preprocessing your inputs. If you need additional code to be executed as part of the setup (e.g. calculation of additional data or defining custom functions), you can do so by placing a file `preprocessing.R` in the folder `inst/compareScenarios`. + +Once you have all the files in place, install your updated project library (or run `devtools::load_all()`). + +## Run compareScenarios + +A simple direct call of `piamPlotComparison::compareScenarios()` may look like this: + +```{r} +library(piamPlotComparison) +compareScenarios( + projectLibrary = "myProjectLibrary", + mifScen = c("path/to/Base.mif", "path/to/NDC.mif"), + mifHist = "path/to/historical.mif", + outputFile = "CompareScenariosExample") +``` + +This creates a pdf called `CompareScenariosExample.pdf` using two runs `Base.mif` and `NDC.mif`, rendering all the sections found in your project library `myProjectLibrary`. + +For further examples and a description of further optional arguments to the function, see `?piamPlotComparison::compareScenarios`. -... +## Interactive use of the Rmd-files + +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 by calling `piamPlotComparison::compareScenarios()` with `outputFormat = "Rmd"` to obtain a (modified) copy of the Rmd-files. + +```{r} +library(piamPlotComparison) +compareScenarios( + projectLibrary = "myProjectLib", + 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 prepare mark} +# 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. -# cs_main.Rmd +# Structure of cs_main.Rmd Internally, `compareScenarios()` calls `rmarkdown::render()` on certain Rmarkdown-files (Rmd-files). To be more precise, `rmarkdown::render()` is called on [cs_main.Rmd](https://github.com/pik-piam/piamPlotComparison/blob/master/inst/compareScenarios/cs_main.Rmd). This file loads the data from the mif-files, preprocesses the data, and includes the section-Rmd-files from the project library at the very end (and optionally further Rmd-files provided by the user, see YAML-parameter `userSectionPath`). diff --git a/vignettes/compareScenarios.html b/vignettes/compareScenarios.html index dfe911d..a8dbdfd 100644 --- a/vignettes/compareScenarios.html +++ b/vignettes/compareScenarios.html @@ -346,8 +346,15 @@

      2024-04-26

      -
      -

      2 Minimal setup

      -

      …

      +
      +

      2 Getting Started

      +
      +

      2.1 Add Rmd files to your +reporting library

      +

      Create a folder inst/compareScenarios in your reporting +library and place one Rmd-file for each section in your document in this +folder. The section-Rmd-files follow the naming pattern +cs_NN_XXXX.Rmd, where NN is replaced by a two +digit number and XXXX is replaced by a short name of the +section.

      +

      The Rmd-files usually contain chunks with plots. For plotting, we +usually use the mip +package or ggplot. The frameworks provides the +data object containing your model runs and historical / +reference data for plotting.

      +

      The framework takes care of preprocessing your inputs. If you need +additional code to be executed as part of the setup (e.g. calculation of +additional data or defining custom functions), you can do so by placing +a file preprocessing.R in the folder +inst/compareScenarios.

      +

      Once you have all the files in place, install your updated project +library (or run devtools::load_all()).

      +
      +
      +

      2.2 Run +compareScenarios

      +

      A simple direct call of +piamPlotComparison::compareScenarios() may look like +this:

      +
      library(piamPlotComparison)
+compareScenarios(
+  projectLibrary = "myProjectLibrary",
+  mifScen = c("path/to/Base.mif", "path/to/NDC.mif"),
+  mifHist = "path/to/historical.mif",
+  outputFile = "CompareScenariosExample")
      +

      This creates a pdf called CompareScenariosExample.pdf +using two runs Base.mif and NDC.mif, rendering +all the sections found in your project library +myProjectLibrary.

      +

      For further examples and a description of further optional arguments +to the function, see +?piamPlotComparison::compareScenarios.

      +
      +
      +

      2.3 Interactive use of +the Rmd-files

      +

      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 by calling piamPlotComparison::compareScenarios() +with outputFormat = "Rmd" to obtain a (modified) copy of +the Rmd-files.

      +
      library(piamPlotComparison)
+compareScenarios(
+  projectLibrary = "myProjectLib",
+  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.

      +
      -
      -

      3 cs_main.Rmd

      +
      +

      3 Structure of +cs_main.Rmd

      Internally, compareScenarios() calls rmarkdown::render() on certain Rmarkdown-files (Rmd-files). To be more precise, rmarkdown::render() is called on cs_main.Rmd. @@ -509,10 +592,10 @@

      0 Info

      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.,

      -
      compareScenarios(
-  projectLibrary = "myProjectLib",
-  mifScen = c(newName1 = "path/to/scen1.mif", newName2 = "path/to/scen2.mif"),
-  ...)
      +
      compareScenarios(
+  projectLibrary = "myProjectLib",
+  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. @@ -527,11 +610,11 @@

      99 Further Info

      config.Rdata files of the scenarios via the YAML-parameter cfgScen, an analysis of the configurations of the scenarios is shown.

      -
      compareScenarios(
-  projectLibrary = "myProjectLib",
-  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"),
-  cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"),
-  ...)
      +
      compareScenarios(
+  projectLibrary = "myProjectLib",
+  mifScen = c("path/to/scen1.mif", "path/to/scen2.mif"),
+  cfgScen = c("path/to/scen1/config.RData", "path/to/scen2/config.RData"),
+  ...)
      From de00b3823551eff5a0b5cc300a164f69a53aa31a Mon Sep 17 00:00:00 2001 From: Falk Benke Date: Mon, 29 Apr 2024 11:12:51 +0200 Subject: [PATCH 4/4] update tutorial --- .buildlibrary | 2 +- CITATION.cff | 2 +- DESCRIPTION | 2 +- vignettes/compareScenarios.Rmd | 13 ++++++++----- vignettes/compareScenarios.html | 20 ++++++++++++-------- 5 files changed, 23 insertions(+), 16 deletions(-) diff --git a/.buildlibrary b/.buildlibrary index 163f9aa..8fe817f 100644 --- a/.buildlibrary +++ b/.buildlibrary @@ -1,4 +1,4 @@ -ValidationKey: '238068' +ValidationKey: '238104' AutocreateReadme: yes AcceptedWarnings: - 'Warning: package ''.*'' was built under R version' diff --git a/CITATION.cff b/CITATION.cff index f3a9b56..d128fab 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -3,7 +3,7 @@ message: If you use this software, please cite it using the metadata from this f type: software title: 'piamPlotComparison: Create comparison plots for your model results' version: 0.0.12 -date-released: '2024-04-26' +date-released: '2024-04-29' abstract: A frameworks to create comparison plots for your model results. authors: - family-names: Benke diff --git a/DESCRIPTION b/DESCRIPTION index cfe539a..66e5e70 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Type: Package Package: piamPlotComparison Title: Create comparison plots for your model results Version: 0.0.12 -Date: 2024-04-26 +Date: 2024-04-29 Authors@R: c( person("Falk", "Benke", , "benke@pik-potsdam.de", role = c("aut", "cre")), person("Christof", "Schoetz", role = "aut") diff --git a/vignettes/compareScenarios.Rmd b/vignettes/compareScenarios.Rmd index 7fa1e76..68e5cd0 100644 --- a/vignettes/compareScenarios.Rmd +++ b/vignettes/compareScenarios.Rmd @@ -22,7 +22,7 @@ knitr::opts_chunk$set( # Overview -`piamPlotComparison` is a lightweight framework to visually compare the results of multiple runs of models, such as [REMIND](https://github.com/remindmodel/remind) or [EDGE-T](https://github.com/pik-piam/edgeTransport). +`piamPlotComparison` is a lightweight framework to visually compare the results of multiple runs of IAMs, such as [REMIND](https://github.com/remindmodel/remind) or [EDGE-T](https://github.com/pik-piam/edgeTransport). It is used in conjunction with a reporting library, such as [remind2](https://github.com/pik-piam/remind2) or [reporttransport](https://github.com/pik-piam/reporttransport). The reporting library includes Rmarkdown-files (Rmd-files) with R-code (e.g., for creating plots, creating tables) as well as descriptive text following some conventions. The framework offers functionality that reads model runs and produces either HTML- and PDF-documents using the Rmd-files via the core function `compareScenarios`. @@ -38,7 +38,7 @@ Create a folder `inst/compareScenarios` in your reporting library and place one The Rmd-files usually contain chunks with plots. For plotting, we usually use the [mip](https://github.com/pik-piam/mip) package or `ggplot`. The frameworks provides the `data` object containing your model runs and historical / reference data for plotting. -The framework takes care of preprocessing your inputs. If you need additional code to be executed as part of the setup (e.g. calculation of additional data or defining custom functions), you can do so by placing a file `preprocessing.R` in the folder `inst/compareScenarios`. +The framework takes care of preprocessing your inputs. If you need additional code to be executed as part of the setup (e.g. calculation of additional data or defining custom functions), you can do so by placing a file `preprocessing.R` in the folder `inst/compareScenarios` in your reporting library. Once you have all the files in place, install your updated project library (or run `devtools::load_all()`). @@ -103,7 +103,6 @@ If provided, also config files are loaded. * The columns `period` (years) and `region` are filtered according to the parameters `yearsScen`, `yearsHist`, and `reg`. * `|+|, |++|, |+++|, ...` are removed from variable names. See also `piamutils::deletePlus`. An additional column `varplus` is added to the data frame, which retains the original name including `+`. This column is used by `mip::showAreaAndBarPlotsPlus()`. -If you need to execute any additional code as part of the general setup, put it into a file `inst/compareScenarios/preprocessing.R` in the project library. Custom code will be executed after the general code. ## Global Variables @@ -114,6 +113,10 @@ It has mostly factor-columns. Thus, a vector of all available regions can be obt Some arguments of the `mip::show...()` plot functions use the functionality provided by the base-R functions `options()` and `getOption()`. In `cs_main.Rmd` there are calls to `options()`, setting values of the global options `mip.mainReg` and `mip.yearsBarPlot`. 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). +## Custom Code + +If you need to execute any additional code as part of the general setup, put it into a file `inst/compareScenarios/preprocessing.R` in your project library. Custom code will be executed after the general code. + If you want to set `mip.histRefModel`, please do so in the `preprocessing.R` file of your project library. # Section-Rmd-files @@ -132,7 +135,7 @@ There is a first section (section number 0) and a last section in the files `cs_ ### 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., +This section contains a file reference table with scenario names and the paths to the respective mif files. It also shows 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., ```{r} compareScenarios( @@ -161,7 +164,7 @@ compareScenarios( ## Plot Functions -The section Rmd-files mostly consist of simple calls of a `show...()`-function from the the [mip](https://github.com/pik-piam/mip) package. These functions are designed to make the creation of re-occurring kinds of plots in `comapreSceanrios` simple. Alternatively, one can build custom plots using `ggplot2`. +The section Rmd-files mostly consist of simple calls of a `show...()`-function from the the [mip](https://github.com/pik-piam/mip) package. These functions are designed to make the creation of re-occurring kinds of plots in `comapreScenarios` simple. Alternatively, one can build custom plots using `ggplot2`. The `mip`-package contains following default plot functions for `comapareScenarios`: diff --git a/vignettes/compareScenarios.html b/vignettes/compareScenarios.html index a8dbdfd..1d55c1d 100644 --- a/vignettes/compareScenarios.html +++ b/vignettes/compareScenarios.html @@ -360,6 +360,7 @@

      2024-04-26

    • 3.2 Loading
    • 3.3 Preprocessing
    • 3.4 Global Variables
      • +
    • 3.5 Custom Code
  • 4 Section-Rmd-files
      @@ -382,7 +383,7 @@

      2024-04-26

      1 Overview

      piamPlotComparison is a lightweight framework to -visually compare the results of multiple runs of models, such as REMIND or EDGE-T.

      +visually compare the results of multiple runs of IAMs, such as REMIND or EDGE-T.

      It is used in conjunction with a reporting library, such as remind2 or reporttransport. The reporting library includes Rmarkdown-files (Rmd-files) with R-code (e.g., for creating plots, creating tables) as well as descriptive text @@ -424,7 +425,7 @@

      2.1 Add Rmd files to your additional code to be executed as part of the setup (e.g. calculation of additional data or defining custom functions), you can do so by placing a file preprocessing.R in the folder -inst/compareScenarios.

      +inst/compareScenarios in your reporting library.

      Once you have all the files in place, install your updated project library (or run devtools::load_all()).

      @@ -530,10 +531,6 @@

      3.3 Preprocessing

      original name including +. This column is used by mip::showAreaAndBarPlotsPlus().
    -

    If you need to execute any additional code as part of the general -setup, put it into a file -inst/compareScenarios/preprocessing.R in the project -library. Custom code will be executed after the general code.

3.4 Global Variables

@@ -554,6 +551,13 @@

3.4 Global Variables

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).

+
+
+

3.5 Custom Code

+

If you need to execute any additional code as part of the general +setup, put it into a file +inst/compareScenarios/preprocessing.R in your project +library. Custom code will be executed after the general code.

If you want to set mip.histRefModel, please do so in the preprocessing.R file of your project library.

@@ -588,7 +592,7 @@

4.2 Special Sections

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 +the paths to the respective mif files. It also shows 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.,

@@ -625,7 +629,7 @@

5.1 Plot Functions

The section Rmd-files mostly consist 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 -comapreSceanrios simple. Alternatively, one can build +comapreScenarios simple. Alternatively, one can build custom plots using ggplot2.

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