README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# Ryassofortran

<!-- badges: start -->
<!-- badges: end -->

The goal of Ryassofortran is to provide convenient R-functions for calling the Fortran90-release of the soil carbon model YASSO15. The Fortran90-release is highly computationally efficient, which makes it ideal for model calibration purposes.


## Installation

### Requirements

* R-version 3.5.0 or higher.
* On Windows systems, Rtools needs to be installed.

You can install the development version of Ryassofortran from GitHub with:

``` r
# install.packages("devtools")
devtools::install_github("YASSOmodel/Ryassofortran")
```

## Introduction

Ryassofortran provides two R-functions: `run_yasso()` and `calibrate_yasso()`. These functions call the respective Fortran90-wrappers `runyasso` and `calyasso`, which in turn call the Fortran90-subroutine `mod5c` containing the YASSO15 model code. In other words, the package makes it possible to use simple R-functions to run a very fast implementation of YASSO15. While both R-functions essentially call the same model code, there are a few distinctive differences in how they work.

**It is important to explicitly define the data types for the R-function inputs.** The Fortran90-wrappers expect certain data types (double or integer) for certain variables and the code will crash or silently fail if the types are not cast correctly in R. See the in-built documentation `?run_yasso` and `?calibrate_yasso` for details.

The `run_yasso()` function is designed for generic use, such as making predictions with YASSO15. The user provides YASSO15 with driver data and initial carbon in a vector. The model "rolls" the carbon forward one time step at a time using the simulated carbon of the current time step as the initial carbon of the next step.

Do soil carbon predictions with `run_yasso()`:

```{r}
library(Ryassofortran)
```

```{r}
# The initial carbon is given as a vector (A, W, E, N, H)
sample_data_run$init
```

```{r example}
# Run the YASSO model with sample parameters and data
soil_c <- run_yasso(
  par = sample_parameters,
  n_runs = sample_data_run$n_runs,
  time = sample_data_run$time,
  temp = sample_data_run$temp,
  prec = sample_data_run$prec,
  init = sample_data_run$init,
  litter = sample_data_run$litter,
  wsize = sample_data_run$wsize,
  leac = sample_data_run$leac
)

# Show the results
round(soil_c, 3)
```

The `calibrate_yasso()` function is highly specialized and not intended for standard use. It is utilized for model calibration at the Finnish Meteorological Institute: In the database used for calibration, there is a measured initial state corresponding to an observed carbon value at each time step. Consequently, the initial carbon is passed to the function as a matrix and the model uses a pre-determined initial state at each time step. Furthermore, the leaching input is a single value instead of a vector, since every calibration dataset has a characteristic leaching.

During calibrations, run YASSO with `calibrate_yasso()`:

```{r}
# The initial carbon is given as a matrix
sample_data_cal$init
```

```{r}
# There is a single leaching value for the entire data set
sample_data_cal$leac
```

```{r}
# Run YASSO during a calibration
soil_c_cal <- calibrate_yasso(
  par = sample_parameters,
  n_runs = sample_data_cal$n_runs,
  time = sample_data_cal$time,
  temp = sample_data_run$temp,
  prec = sample_data_run$prec,
  init = sample_data_cal$init,
  litter = sample_data_cal$litter,
  wsize = sample_data_cal$wsize,
  leac = sample_data_cal$leac
)

# Show the results
round(soil_c_cal, 3)
```

## How to use

Shape and typecast the driver data into the correct format. Call YASSO with the R-function that corresponds to your use case. Examine the simulated results.

When first starting out, it is recommended to take a look at the inbuilt package documentation:

1. Load the package in R with `library(Ryassofortran)`.

2. Open the documentation for the R-functions with `?run_yasso` and `?calibrate_yasso`.

3. Open the documentation for sample datasets with `?sample_data_run` and `?sample_data_cal`.

4. Run the examples in the R-functions' documentation using the sample datasets. Note, that the datasets have distinct shapes and each function only works with the corresponding dataset.

As mentioned above, the types of the function inputs need to be defined explicitly in R. The type of each input should be cast with the `as.<type>` commands as presented in the R-function documentation. For example, the inputs `n_runs`, `time` and `litter` are typecast with `as.integer`, `as.double` and `as.matrix`, respectively. See the scripts that create the sample data in `Ryassofortran/data-raw/` for a demonstration.