---
title: "rOpenscmRunner"
description: "Simulate the climate response to emissions using different simple climate models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rOpenscmRunner}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```
## Introduction

Using `rOpenscmRunner`, you can simulate the climate response to emissions. To do this, it uses the python package
[openscm-runner](https://openscm-runner.readthedocs.io). This makes it possible to run several simple climate models
using a unified interface. At the moment, the models FaIR, MAGICC, and Cicero-SCM are supported by `openscm-runner`,
and therefore usable from `rOpenscmRunner`.

`openscm-runner` only supports emissions-driven runs. This means that you provide an emissions scenario specifying
the emissions of forcing agents over time, choose which model(s) you want to run with which configuration(s) and
which outputs you are interested in, and hand this all over to `rOpenscmRunner` and you will get back the simulated
climate response(s), e.g. temperatures. The available response variables depend on the chosen model and configuration.

## Installation

For installation of `rOpenscmRunner` an additional repository has to be added in R:

```r
options(repos = c(CRAN = "@CRAN@", pik = "https://rse.pik-potsdam.de/r/packages"))
```
The additional repository can be made available permanently by adding the line above to a file called `.Rprofile`
stored in the home folder of your system (`Sys.glob("~")` in R returns the home directory).

After that the most recent version of the package can be installed using `install.packages`:

```r
install.packages("rOpenscmRunner")
```

Additionally, you will need a Python installation and the `openscm-runner` Python package installed, as well as some
climate models. If you don't have a Python installation so far, you can find one at
[anaconda](https://www.anaconda.com/products/distribution). Use the package management of your Python distribution
to install `openscm-runner`. You can then specify which simple climate models you want to also install.
If you use `pip`, choose what you need and run from the command line:

```bash
$ pip install --user openscm-runner[fair]  # openscm-runner and everything needed to run the model FaIR
$ pip install --user openscm-runner[magicc]  # openscm-runner and everything needed to integrate with the model MAGICC
$ pip install --user openscm-runner[models]  # openscm-runner and all available models
```

If you are using `conda` instead of `pip`, or want to know further details about the installation, check the
[openscm-runner installation documentation](https://openscm-runner.readthedocs.io/en/latest/installation.html).

If you want to run the MAGICC model, you also have to install it. Download the most recent version from
[magicc.org](https://magicc.org/download/magicc7). Extract it to a location suitable to you, and copy the default
configuration from the `run/defaults/` folder into the `run/` folder.

## Setup

FaIR and Cicero-SCM are installed via the Python package management or included in `openscm-runner`, so
it knows where to find them. However, MAGICC is installed separately, so you have to tell `rOpenscmRunner` where to
find it using the `rOpenscmRunner::setup` function. Additionally, you have to also provide a path to a folder where
MAGICC can store temporary files:

```{r}
rOpenscmRunner::setup(magiccExecutable7 = "/path/to/magicc/bin/magicc",  # nolint: absolute_path_linter
                      magiccWorkerRootDir = "/path/to/temp/folder")  # nolint: absolute_path_linter
```
If you are on windows, you have to give the full path to the `magicc.exe` file in the MAGICC installation in the
`bin/` folder. On Linux, give the full path to the `magicc` file in the `bin/` folder in the MAGICC installation.
The temporary folder must not be inside the `magicc` folder where the `magiccExecutable7` is. You can simply use
R's standard temporary folder like this:

```r
rOpenscmRunner::setup(magiccWorkerRootDir = tempdir())
```

Using the same mechanism, you can also configure other parts of the MAGICC integration, but they are not required:
```{r}
rOpenscmRunner::setup(magiccWorkerNumber = 4)
```
The default for the number of workers is to use as many workers as there are processors in your system. This should
be a sensible default on laptops and workstations, but probably needs manual setup on shared machines like compute
clusters.

All settings supplied via `rOpenscmRunner::setup()` are remembered for the duration of your current R session. If you
don't want to call `rOpenscmRunner::setup()` in each session, you can also supply these settings via environment
variables, check the documentation of `rOpenscmRunner::setup()` for details.

## Usage

To run simple climate model(s), use the `rOpenscmRunner::run()` function. It takes the emission scenario(s) as a
`data.frame` in a format like the IAMC format for scenarios. In particular, it is a `data.frame` where each row is
a time series and the columns are `model` for the model that produced the emissions scenario, `scenario` for a name
of the scenario, `region` for the area (most likely, `World` for simple climate models), and `variable` and
`unit` to specify what is in the timeseries. The remaining columns are the time points, most likely years.
An example for a very short and incomplete emissions scenario would be:
```{r}
# create very minimal emissions scenario.
df <- data.frame(
  model = c("rand", "rand"),
  scenario = c("weirdEMI", "weirdEMI"),
  region = c("World", "World"),
  variable = c("Emissions|CO2", "Emissions|CH4"),
  unit = c("Mt CO2 / yr", "Mt CH4 / yr"),
  "2015" = c(9., 12.),
  "2020" = c(10., 11.),
  check.names = FALSE
)
df
```
Note the usage of `check.names = FALSE` to be able to use years as column names.

With the `rOpenscmRunner::run()` function, you can then simulate all scenarios in the data frame at once:

```r
# simulate the scenario(s) using MAGICC7 with default settings.
result <- rOpenscmRunner::run(climateModelsConfigs = list("MAGICC7" = NULL), scenarios = df)
```

You will then find the simulated climate scenario in the same format as the input scenarios in `result$df` and any
metadata generated by the climate model in `result$metadata`. Note that if you run these examples as-is, you will
get a lot of warnings and errors from MAGICC because the example emissions scenario is so incomplete. For serious
work, you will obviously need a complete emissions scenario.

You can also change configuration values in the models or even run multiple configurations at once and
request other outputs from the model(s). As an example, we simulate the surface temperature and sea level rise
using MAGICC with two different non-standard climate sensitivity settings. Note that we have to include
`CORE_CLIMATESENSITIVITY` in `outConfig` so that we can distinguish the runs in the result data frame.

```r
# output sea level rise and surface temperature for two different climate sensitivity settings.
res <- rOpenscmRunner::run(
  climateModelsConfigs = list("MAGICC7" = list(list("CORE_CLIMATESENSITIVITY" = 3.),
                                               list("CORE_CLIMATESENSITIVITY" = 4.))),
  scenarios = df,
  outConfig = list("MAGICC7" = list("CORE_CLIMATESENSITIVITY")),
  outputVariables = list("Surface Temperature", "Sea Level Rise")
)
```

The available configuration settings depend on the climate model and have to be looked up in the respective
documentation. The names of `outputVariables` are standardized for the most common output variables by
`openscm-runner` according to the names used in the [Special Report: Global Warming of 1,5°](https://www.ipcc.ch/sr15/).
You can find them all in the [SR15 database](https://data.ene.iiasa.ac.at/iamc-1.5c-explorer)
in the tab "Documentation" in the section "Variables" (available after login, guest login works). Some climate
models provide additional non-standard outputs, if you want to request any of those, you have to use the non-standard
name of the climate model.

It is also possible to run multiple models at once. Expanding on the sea level rise example, we could also add
a run of FaIR in the default configuration:
```r
# output sea level rise and surface temperature for two different climate
# sensitivity settings for MAGICC and a default run of FaIR for comparison.
res <- rOpenscmRunner::run(
  climateModelsConfigs = list("MAGICC7" = list(list("CORE_CLIMATESENSITIVITY" = 3.),
                                               list("CORE_CLIMATESENSITIVITY" = 4.)),
                              "FaIR" = NULL),
  scenarios = df,
  outConfig = list("MAGICC7" = list("CORE_CLIMATESENSITIVITY")),
  outputVariables = list("Surface Temperature", "Sea Level Rise")
)
```

## Debugging

If you run into problems and errors, it might be easier to try and run `openscm-runner` directly from Python to
isolate your problem. You will get more complete error messages from `openscm-runner` when run directly from Python.