Skip to content
Snippets Groups Projects
Commit 14a6479c authored by Michaja Pehl's avatar Michaja Pehl
Browse files

fix typos and nomenclature 

  - R packages are packages (that are loaded with the library()
    function)
  - REMIND is optimising scenarios, and not simulating anything
  - as this is intended for people newly coming to REMIND, we don't want
    to start out teaching them the wrong terms
parent 8f0ed9c0
No related branches found
No related tags found
1 merge request!31fix typos and nomenclature
Hide whitespace changes
Inline Side-by-side
tutorials/2_RunningREMIND.md
+ 10
− 8
View file @ 14a6479c
......@@ -16,7 +16,8 @@ Felix Schreyer (<felix.schreyeru@pik-potsdam.de>), Lavinia Baumstark (<baumstark
1. Your first run
==================
This section will explain how you start your first run in REMIND.
Default Configurations (config/default.cfg)
......@@ -28,7 +29,7 @@ a. The first part, MODULES, contains the various modules used in REMIND and vari
``` bash
cfg$gms$<module name
```
```
b. The SWITCHES and FLAGS section are various settings to control, for e.g., how many iterations to run, which technologies to run, which SSP to use, start and end year of model run etc. See the fourth section, explanations of switches and flags, to know more.
......@@ -47,7 +48,7 @@ Your config file should look like this:
<p class="caption">
Example for a scenario_config of REMIND
</p>
Save the config file as a csv file with `;` as delimiter. You can check that, for example, by opening the csv in a text editor. If the delimiter is not `;`, change it in Windows under ***Control Panel*** -> ***Region*** -> ***Additional Settings*** -> ***List separator***.
To finally start REMIND with this config file, you need to run the R-script ***start_bundle.R*** on the cluster on this config file. For this:
......@@ -67,7 +68,7 @@ For starting one single or a bundle of runs via scenario_config.csv you use the
``` r
nohup Rscript start_bundle.R config/scenario_config.csv &
```
```
Now, keep your fingers crossed that everything works as it should.The process of your job submission is documented in the file nohup.out that you created with the nohup command. After a couple of minutes, you should see something like `Submitted Batch Job ...` in the nohup.out file. This means that your run has been started. To see how far your run is or whether it was stopped due to some problems, go to the `Output` folder and type
``` bash
......@@ -97,13 +98,14 @@ in the terminal.
2. What happens during a REMIND run?
=====================================
This section will give some technical introduction into what happens after you have started a run. It will not be a tutorial, but rather an explanation of the different parts in the modeling routine. The whole routine is illustrated in Figure 1. The core of the model is the optimization written in GAMS. However, there is some pre-processing of the input data and some post-processing of the output data using R scripts.
<img src="figures/REMIND_flow.png" alt="REMIND modeling routine" width="100%" />
<p class="caption">
REMIND modeling routine
</p>
​
3. What happens once you start REMIND on the Cluster?
=======================================================
......@@ -117,8 +119,8 @@ The optimization in REMIND requires a lot of input data. For example, the model
``` bash
/p/projects/rd3mod/inputdata/sources.
```
The data are mostly in csv files. During the input data preparation, these files are read and processed, using functions from the *moinput* library. Input data are available on country-level. Then, depending on the regionmapping file you chose in the config file of your run, the country-level data are aggregated into regions, e.g. to LAM (Latin America), EUR (Europe) and so on. Finally, the data are stored as .cs3r or .cs4r files in various input folders of your REMIND directory. These files are basically tables, too, that you can open with a text editor or Excel. For example, you find the input file `p_histCap.cs3r` in your REMIND directory under `core/input`. It provides the model with historically observed values of installed capacities of some technologies in the respective regions.
The data are mostly in csv files. During the input data preparation, these files are read and processed, using functions from the *moinput* package. Input data are available on country-level. Then, depending on the regionmapping file you chose in the config file of your run, the country-level data are aggregated into regions, e.g. to LAM (Latin America), EUR (Europe) and so on. Finally, the data are stored as .cs3r or .cs4r files in various input folders of your REMIND directory. These files are basically tables, too, that you can open with a text editor or Excel. For example, you find the input file `p_histCap.cs3r` in your REMIND directory under `core/input`. It provides the model with historically observed values of installed capacities of some technologies in the respective regions.
The regional resolution of the run is set in the config/default.cfg by
``` bash
cfg$regionmapping
......@@ -135,7 +137,7 @@ The actual REMIND is written in GAMS, a programming software to numerically solv
c) Output Processing
----------------------
The output processing works with a number of R functions from the **remind** library (most of them start with `report... .R`). The wrapper function **convGDX2MIF.R** writes the most relevant output into the so-called **.mif** file. Again, it is a table that you can open in Excel for example. You find under `output` in the folder of your REMIND run as
The output processing works with a number of R functions from the **remind** package (most of them start with `report... .R`). The wrapper function **convGDX2MIF.R** writes the most relevant output into the so-called **.mif** file. Again, it is a table that you can open in Excel for example. You find under `output` in the folder of your REMIND run as
``` bash
REMIND_generic_YourRun.mif
......
tutorials/5_AnalysingModelOutputs.md
+ 26
− 25
View file @ 14a6479c
......@@ -22,23 +22,23 @@ Felix Scheyer (<felix.schreyer@pik-potsdam.de>), Isabelle Weindl (<weindl@pik-po
1. Introduction
===============
After having successfully started and accomplished a simulation run, the next step is to evaluate the simulation results.
After having successfully started and completed a scenario run, the next step is to evaluate the results.
There are plentiful ways to look at and analyze REMIND results. This tutorial gives an overview on different tools and options that can be used.
For each simulation, results are written to a folder that is created automatically as a combination of **model title** name and the **current date** inside the **output** folder of the model.
For each scenario, results are written to a folder that is created automatically as a combination of **scenario title** name and the **current date** inside the **output** folder of the model.
2. Model output files
=====================
As mentioned in section 2, the two main output files you will typically care about are the *fulldata.gdx* and the *REMIND_generic_NameofYourRun.mif* files in the *output* folder of your run. The *fulldata.gdx* is the actual technical output of the GAMS optimization and contains all the variables, parameters, sets etc. (the differences between these GAMS objects are explained in tutorial 2) of the REMIND model. However, this gdx-file ia mainly interesting once you actually work on the GAMS code and want to check specific the variables and their values. If you simply want to look at REMIND results of your run or use it for further data analysis and plotting, you would open the *REMIND_generic_NameofYourRun.mif* which is basically a csv-file in a certain standardized format used in the Integrated Assessment Modeling community.
As mentioned in tutorial 2, the two main output files you will typically care about are the *fulldata.gdx* and the *REMIND_generic_NameofYourRun.mif* files in the *output* folder of your run. The *fulldata.gdx* is the actual technical output of the GAMS optimization and contains all the variables, parameters, sets etc. (the differences between these GAMS objects are explained in tutorial 2) of the REMIND model. However, this gdx-file is mainly interesting once you actually work on the GAMS code and want to check specific the variables and their values. If you simply want to look at REMIND results of your run or use it for further data analysis and plotting, you would open the *REMIND_generic_NameofYourRun.mif* which is basically a csv-file in a certain standardized format used in the Integrated Assessment Modeling community.
Looking at the *REMIND_generic_NameofYourRun.mif*, the column **scenario** gives the name of the run (that you specified in the first column of your config file when starting the run). The column **region** provides an three-letter acronym of the region (e.g. EUR -> EU, SSA -> Sub-Saharan Africa). The column **variable** represents the variable you are looking at (To avoid confusion with the above: It does not necessarily represent a variable in the GAMS code of REMIND. The mif-file is a synthetized output generated from *fulldata.gdx* by post-processing Rscripts from the *remind* library). Scrolling through the **variable** column, you will get an impression of the myriad of outputs the REMIND model permits you to explore.
Looking at the *REMIND_generic_NameofYourRun.mif*, the column **scenario** gives the name of the run (that you specified in the first column of your config file when starting the run). The column **region** provides an three-letter acronym of the region (e.g. EUR -> EU, SSA -> Sub-Saharan Africa). The column **variable** represents the variable you are looking at (To avoid confusion with the above: It does not necessarily represent a variable in the GAMS code of REMIND. The mif-file is a synthetized output generated from *fulldata.gdx* by post-processing Rscripts from the *remind* package). Scrolling through the **variable** column, you will get an impression of the outputs the REMIND model permits you to explore.
3. Loading and analyzing model output in R
==============================
### 3.1 Access Cluster
### 3.1 Access the Cluster
To analyze your model results, you can load the output of the mif-file into a local session in RStudio. To get the file from the cluster, you can download the mif-file, for example, via WinSCP. You can read more details on how to access the cluster here:
......@@ -46,9 +46,9 @@ To analyze your model results, you can load the output of the mif-file into a lo
https://redmine.pik-potsdam.de/projects/mo/wiki/Getting_ready_to_use_the_Cluster
### 3.2 Load mif file as Magpie Object
### 3.2 Load a mif file as a Magpie Object
You can load the mif-file of your run into a magpie object from the **magclass** R library by
You can load the mif-file of your run into a magpie object from the **magclass** R package by
``` r
out <- read.report("Path/to/your/mif-file", as.list = F)
......@@ -63,14 +63,14 @@ you see the dimension of the magpie object. Magpie objects are basically arrays,
``` r
out["EUR", c("y2020","y2050"), "FE|Transport (EJ/yr)"]
```
Instead of these objects from the R library **magclass**, you can also use dataframes from the R library **quitte**. Arrays are generally better for doing calculations, while dataframes are better for plotting. You will find out after a while which way works best for you. The **quitte** dataframes are probably better for output analysis because this is a lot about plotting. For reading in the *.mif* file as a dataframe, you have to load the library **quitte** and then run the command
Instead of these objects from the R package **magclass**, you can also use data frames from the R package **quitte**. Arrays are generally better for doing calculations, while data frames are better for plotting. You will find out after a while which way works best for you. The **quitte** data frames are probably better for output analysis because this is a lot about plotting. For reading in the *.mif* file as a data frame, you have to load the package **quitte** and then run the command
### 3.3 Load mif file as quitte Object
### 3.3 Load a mif file as a quitte Object
``` r
mifdata <- read.quitte(PathtoYourMifFile.mif)
mifdata <- read.quitte('PathtoYourMifFile.mif')
```
The data is now stored in the *quitte* object *mifdata*. In RStudio, selecting it and hitting F2 will show you its content. Usually, you will want to filter for some regions, variables, periods that you are interested in. For example, like this:
The data is now stored in the *quitte* object *mifdata*. In RStudio, selecting it (the text *mifdata* in the editor window) and hitting F2 will show you its content. Usually, you will want to filter for some regions, variables, periods that you are interested in. For example, like this:
``` r
df <- filter(mifdata,
......@@ -79,9 +79,9 @@ df <- filter(mifdata,
scenario %in% c('BAU'),
period %in% c(2005,2030,2050))
```
### 3.4 Load gdx file as magpie object
### 3.4 Load a gdx file as a Magpie Object
Finally, you can also load the content of the **fulldata.gdx** via the function **readGDX** of the **gdx library** (<https://github.com/pik-piam/gdx>) into a magpie file to directly access the GAMS output. Here is an example of how **readGDX** is used:
Finally, you can also load the content of the **fulldata.gdx** via the function **readGDX** of the **gdx** package (<https://github.com/pik-piam/gdx>) into a magpie file to directly access the GAMS output. Here is an example of how **readGDX** is used:
``` r
pe2se <- readGDX(gdx,"pe2se")
......@@ -105,7 +105,7 @@ The automated model analysis (summary and validation) is an important example of
For a first overview and for not getting lost in the huge amount of variables you can look at the *REMIND_summary_[title].pdf*. This .pdf-file will give you an overview on the model results and guides you through the story.
### 4.3 The Whole Range of Validation
A standard validation PDF *REMIND_validation_[title].pdf* consists of hundreds of evaluation outputs. By evaluating the model outputs on such a broad level rather than focusing only on key outputs, it allows getting a more complete picture of the corresponding simulation. The table of contents of the validation pdf gives a good overview about the breadth of model outputs that can be simulated with a REMIND standard simulation, even though the validation pdf only shows a subset of possible model outputs.
A standard validation PDF *REMIND_validation_[title].pdf* consists of hundreds of evaluation outputs. By evaluating the model outputs on such a broad level rather than focusing only on key outputs, it allows getting a more complete picture of the corresponding scenario. The table of contents of the validation pdf gives a good overview about the breadth of model outputs that can be generated with a REMIND standard scenario, even though the validation pdf only shows a subset of possible model outputs.
5. Interactive scenario analysis
......@@ -115,20 +115,21 @@ The automated model validation is a good tool for visually evaluating a broad ra
### 5.1. AppResults
To overcome this issue, we developed the interactive scenario analysis and evaluation tools appResults and appResultsLocal as part of the library **shinyresults** (<https://github.com/pik-piam/shinyresults>), which show evaluation plots for multiple scenarios including historical data and other projections based on an interactive selection of regions and variables. You can use this tool by running the following R command, which will automatically collect all runs and visualize them:
To overcome this issue, we developed the interactive scenario analysis and evaluation tools appResults and appResultsLocal as part of the package **shinyresults** (<https://github.com/pik-piam/shinyresults>), which show evaluation plots for multiple scenarios including historical data and other projections based on an interactive selection of regions and variables. You can use this tool by running the following R command, which will automatically collect all runs and visualize them:
``` r
shinyresults::appResults()
```
This command opens an interactive window, where you can select the simulations that you want to evaluate.
This command opens an interactive window, where you can select the scenarios that you want to evaluate.
<img src="figures/appResults_window.png" alt="Interactive Results app" width="70%" />
<p class="caption">
Interactive Results app
</p>
You can use filters to select a subset of all runs stored in the output folder of the model, for example by searching for runs that have been finished at a certain day or by searching for keywords in the title of the simulation runs:
You can use filters to select a subset of all runs stored in the output folder of the model, for example by searching for runs that have been finished at a certain day or by searching for keywords in the title of the scenarios:
<img src="figures/appResults_runselection.png" alt="Run selection by using a filter" width="70%" />
<p class="caption">
......@@ -139,7 +140,7 @@ If you run the following command in the output folder of your local computer you
``` r
shinyresults::appResultsLocal()
```
Another tool for analyzing model output on your local computer is the scneario tool from the mip library. You can open it from the R console by:
Another tool for analyzing model output on your local computer is the scenario tool from the mip package. You can open it from the R console by:
``` r
mip::scenTool()
......@@ -158,7 +159,7 @@ cfg$output <- c("reporting","validation","rds_report","validationSummary","dashb
### 6.2. Execution of model-internal output scripts in the command window
Output scripts that are included in the folders **scripts/output/single** and **scripts/output/comparison** can also be executed via command window. To do so, windows users can open a command line prompt in the REMIND model folder by using **shift** + **right click** and then selecting *open command window here* option.
Output scripts that are included in the folders **scripts/output/single** and **scripts/output/comparison** can also be executed via a command window. To do so, windows users can open a command line prompt in the REMIND model folder by using **shift** + **right click** and then selecting *open command window here* option.
In the command prompt, use the following command:
......@@ -173,23 +174,23 @@ You are now asked to choose the output mode: 1: Output for single run 2: Compari
Executing output scripts via command window
</p>
In both cases, you can choose from the list of available model simulations, for which runs you want to conduct the model output analysis.In the next step, you can interactively indicate which model-internal output scripts you want to execute.
In both cases, you can choose from the list of available model scenarios, for which runs you want to conduct the model output analysis. In the next step, you can interactively indicate which model-internal output scripts you want to execute.
Now, the selected scripts are executed. After completion, the results are written in the respective folder of the simulation run (combination of **model title** name and the **current date** inside the **output** folder of the model).
Now, the selected scripts are executed. After completion, the results are written in the respective folder of the run (combination of **model title** name and the **current date** inside the **output** folder of the model).
7. Analysis of outputs with the remind library
7. Analysis of outputs with the remind package
===============================================
If you want to go beyond visual output analysis and predefined output evaluation facilitated by scripts in the model folders **scripts/output/single** and **scripts/output/comparison**, you can use the functionality of the R package *remind*. This library contains a list of common functions for extracting outputs from the REMIND model which are also the basis for the generation of the automated validation pdf. For a quick overview on the functions which are included in the library, you can scan the folder **remind/R**.
If you want to go beyond visual output analysis and predefined output evaluation facilitated by scripts in the model folders **scripts/output/single** and **scripts/output/comparison**, you can use the functionality of the R package *remind*. This package contains a list of common functions for extracting outputs from the REMIND model which are also the basis for the generation of the automated validation pdf. For a quick overview on the functions which are included in the package, you can scan the folder **remind/R**.
For making yourself familiar with this library, you can open a R/RStudio session and set the REMIND model folder as working directory. This can be done by using the following command:
For making yourself familiar with this package, you can open a R/RStudio session and set the REMIND model folder as working directory. This can be done by using the following command:
``` r
setwd("/path/to/your/remind/model/folder")
```
Then, load the library and call the help pages:
Then, load the package and call the help pages:
``` r
library(remind)
......
tutorials/6_Advanced_ChangeInputs.md
+ 2
− 2
View file @ 14a6479c
......@@ -36,11 +36,11 @@ ssh-keygen -p
```
It is recommended to first copy the existing key (e.g. id_dsa into id_dsa-local) and remove the passphrase of this copy and copy it to your machine.
If you plan to run REMIND not with the default regional resolution you have to take care that REMIND starts from a gdx with the correct regional resolution. Either you can use one from an older run with the corresponding regional resolution or you can construct a new gdx with the correct regional resolution from a gdx in a different regional resolution by using the function gdx_rename from the library(gdx) (e.g. gdx_rename("input.gdx",set_name="all_regi",c(REF="RUS",CAZ="ROW",...,MEA="MEA",USA="USA"))).
If you plan to run REMIND not with the default regional resolution you have to take care that REMIND starts from a gdx with the correct regional resolution. Either you can use one from an older run with the corresponding regional resolution or you can construct a new gdx with the correct regional resolution from a gdx in a different regional resolution by using the function gdx_rename from the package (gdx) (e.g. gdx_rename("input.gdx",set_name="all_regi",c(REF="RUS",CAZ="ROW",...,MEA="MEA",USA="USA"))).
Adding New Input Data
======================
The input data for REMIND are generated by using the R-libraries *moinput* and *madrat* (https://github.com/pik-piam/madrat). While *moinput* contains all calculations tailored to REMIND-input-data, the library *madrat* provides the general wrapper functions and helpful tools. For further information read the vignettes part of the R-packages.
The input data for REMIND are generated by using the R-libraries *moinput* and *madrat* (https://github.com/pik-piam/madrat). While *moinput* contains all calculations tailored to REMIND-input-data, the package *madrat* provides the general wrapper functions and helpful tools. For further information read the vignettes part of the R-packages.
tutorials/7_Advanced_ChangeCode.md
+ 2
− 2
View file @ 14a6479c
......@@ -92,7 +92,7 @@ How to make a new module or realization in REMIND
If you want to create a **new module** in REMIND first think about the interfaces between the core code and your new module. This helps you to design your module.
For creating a new module you can use the function **module_skeleton** from the R library "lucode". Start R and set the working directory to the folder of your REMIND version you want to make the changes (e.g. setwd(../../remind_20/trunk)).
For creating a new module you can use the function **module_skeleton** from the R package "lucode". Start R and set the working directory to the folder of your REMIND version you want to make the changes (e.g. setwd(../../remind_20/trunk)).
``` r
library(lucode)
......@@ -101,7 +101,7 @@ module.skeleton(100,"bla",c("on","off"))
It creates all folders and gams files for your new module "100_bla" with the realizations "on" and "off". More information about the function module_skeleton you can find at the help desk of R.
For creating a **new realization** of an existing module you can also use the function module_skeleton of the R library "lucode". Go into the folder "module" of your REMIND version and there in the folder of the module you want to make a new realization for (e.g. "module/100_bla", "module/10_climate"). Now you can start R and set the working directory to the head folder of your REMIND version you want to introduce the new realization.
For creating a **new realization** of an existing module you can also use the function module_skeleton of the R package "lucode". Go into the folder "module" of your REMIND version and there in the folder of the module you want to make a new realization for (e.g. "module/100_bla", "module/10_climate"). Now you can start R and set the working directory to the head folder of your REMIND version you want to introduce the new realization.
``` r
library(lucode)
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment