Model_methods.Rmd

---
title: "Model structure and related functions"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## Methods

We use several different functions to create a working model of the garden intervention.

### Chance Event Function: Generating Conditional Values

We use the `chance_event` function to generate conditional values with:

```{r chance_event}
source("functions/chance_event.R")
```


$$
   occurrence =
   \begin{cases}
   rbinom(length(value\_if), 1, chance) & if  !one\_draw \\
   rbinom(1, 1, chance) & if  one\_draw
   \end{cases}
$$

and final values with:

$$
   chance\_event = occurrence \cdot value\_if + (1 - occurrence) \cdot value\_if\_not
$$

### Value Varier Function: Generating Synthetic Data

```{r vv}
source("functions/vv.R")
```

We use the `vv` function to generate synthetic data with varying means and coefficients of variation with:

-   $n$: Number of data points to generate.
-   $var\_mean$: Mean value for the data.
-   $var\_CV$: Coefficient of Variation (CV) for the data.
-   $distribution$: Distribution of the data (e.g., normal distribution).
-   $absolute\_trend$: Absolute trend to add to the data.
-   $relative\_trend$: Relative trend to apply to the data.
-   $lower\_limit$: Lower limit for generated data.
-   $upper\_limit$: Upper limit for generated data.

These are used to calculate annual means:

-   If both absolute and relative trends are absent, the annual means remain constant:

$$
    annual\_means = var\_mean
$$

-   If an absolute trend is present, annual means are adjusted linearly:

$$
    annual\_means = var\_mean + absolute\_trend \cdot (0, 1, \ldots, n-1)
$$

-   If only a relative trend is present, annual means change multiplicatively:

$$
    annual\_means = var\_mean \cdot (1 + relative\_trend / 100)^{(0, 1, \ldots, n-1)}
$$

-   Generate random data points based on the specified distribution using calculated annual means:

$$
    out \sim \mathcal{N}(annual\_means, \lvert annual\_means \rvert \cdot \frac{var\_CV}{100})
$$

-   If specified, limit data points to the defined lower and upper limits:

$$
    out = \max(out, lower\_limit), \quad out = \min(out, upper\_limit)
$$

### Net Present Value (NPV)

```{r NPV}
source("functions/discount.R")
```

The discounted value of a time series value $x_t$ at time $t$ can be calculated using the formula:

$$
   \text{Discounted Value}_t = \frac{x_t}{\left(1 + \frac{\text{Discount Rate}}{100}\right)^{t-1}}
$$

Where:

-   $x_t$ is the value at time $t$,

-   $\text{Discount Rate}$ is the discount rate provided to the function,

-   $t$ is the time period (starting from 1).

2.  **Net Present Value (NPV)** (if `calculate_NPV` is set to `TRUE`): The Net Present Value of a time series with discounted values can be calculated as the sum of all discounted values:

$$
    \text{NPV} = \sum_{t=1}^{n} \frac{x_t}{\left(1 + \frac{\text{Discount Rate}}{100}\right)^{t-1}}
$$

Where $n$ is the number of time periods in the time series.

## Monte Carlo Simulation Function

```{r MC}
source("functions/mcSimulation.R")
```

We use the `mcSimulation` function to perform Monte Carlo simulations to estimate model outputs based on provided parameters and a model function.

## Monte Carlo Simulation Process

The Monte Carlo simulation process generates a set of estimated model outputs based on random input samples, providing a distribution of potential outcomes including:

-   random input generation with $x_1, x_2, \ldots, x_n$ as a set of $n$ random input samples drawn from a given distribution, representing the input parameters of the model.

-   a model function $f(x)$ that maps the input data $x$ to the corresponding model output $y$. This can be expressed as:

$$
     y_i = f(x_i), \quad i = 1, 2, \ldots, n
$$

-   estimated model outputs $\hat{y}_1, \hat{y}_2, \ldots, \hat{y}_n$ obtained by applying the model function to the random input samples:

$$
     \hat{y}_i = f(x_i), \quad i = 1, 2, \ldots, n
$$