---
title: "sfcr_multis"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{sfcr_multis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The objective of this vignette is to explore all the possibilities of simulating many similar models with the flexible `sfcr_multis()` function.

Load the `sfcr` package:

```{r setup}
library(sfcr)
library(tidyverse)
```

I'm going to use model SIM to go through this example as it is a very simple model.

As always, we start by writing down the equations and external variables:

```{r}
eqs <- sfcr_set(
  TXs ~ TXd,
  YD ~ W * Ns - TXs,
  Cd ~ alpha1 * YD + alpha2 * Hh[-1],
  Hh ~ YD - Cd + Hh[-1],
  Ns ~ Nd,
  Nd ~ Y / W,
  Cs ~ Cd,
  Gs ~ Gd,
  Y ~ Cs + Gs,
  TXd ~ theta * W * Ns,
  Hs ~ Gd - TXd + Hs[-1]
)

external <- sfcr_set(
  Gd ~ 20, 
  W ~ 1, 
  alpha1 ~ 0.6, 
  alpha2 ~ 0.4, 
  theta ~ 0.2
  )
```

And simulating a baseline model:

```{r}
baseline <- sfcr_baseline(eqs, external, periods = 60, hidden = c("Hh" = "Hs"))
```

The `sfcr_multis()` function is a S3 generic that currently can be used in three ways:

1. To generate many baseline models based on a expanded set of external equations;
2. To generate many scenario models based on a expanded set of shocks;
3. To generate many scenario models that applies the same shock to many baseline models.

The idea of this function is that we want to have many models that are very similar but differs in one specific way. That's why it accept two arguments that are not in the `sfcr_baseline()` or `sfcr_scenario()` functions:

1. Expanded: an object created with `sfcr_expand()` or with `sfcr_multis()`. It is here that we feed the models with its varying characteristics;
2. Fixed: This is the part of the models that are going to remain fixed. It is a set of equations if the expanded argument is a expanded set of external variables; a baseline model if the expanded argument takes an expanded set of shocks; and it is a shock if the expanded argument takes many baseline models.

Furthermore, the `periods` argument must be defined by the user. Finally, the `...` argument accept any extra argument that feed the `sfcr_baseline()` and `sfcr_scenario()` functions that are called under the hood.

## 1. Many baseline models based on a expanded set of external equations

This option allows the user to select one variable (e.g. `alpha1`) and run many models that are only different in their values of that variable.

The first step is to expand the external set with the `sfcr_expand()` function. It has three arguments:

1. x - the set to be expanded
2. variable - the name of the variable
3. values - the values that the variable will take

```{r}
x_external <- sfcr_expand(external, alpha1, seq(0.5, 0.9, 0.02))
```

We then use this variable to simulate all the models at once with `sfcr_multis()`:

```{r}
mlt_sim1 <- sfcr_multis(x_external, eqs, 50)
```

The resulting `mlt_sim1` object is a `sfcr_mlt` `list`. Every item in this list is a `sfcr_tbl` object that looks like the output generated by `sfcr_baseline()` or `sfcr_scenario()` but has an extra column, named as `simulation`, that indicates which of the simulation this item represents.

```{r}
str(mlt_sim1[[1]])
```


## 2. Many scenarios based on a expanded set of shocks

The idea here is to expand a `sfcr_shock` set to simulate many scenario models. In this example, I'm going to show how to apply different shocks to the `alpha2` parameter:

```{r}
shock1 <- sfcr_shock(
  variables = sfcr_set(
    alpha2 ~ 0.3
  ),
  start = 5,
  end = 50
)

x_shock <- sfcr_expand(shock1, alpha2, seq(0.1, 0.4, 0.05))

mlt_sim2 <- sfcr_multis(x_shock, baseline, 50)
```

As we can see, the structure of these models are the same as before:

```{r}
str(mlt_sim2[[1]])
```

## 3. Many scenarios based on the same shock applied to many baseline models

Finally, the last option is to apply the same shock to many baseline models, generating many scenarios. In this example, I will use the `mlt_sim1` object as the `expanded` argument and the `shock1` shock as the `fixed` argument:

```{r}
mlt_sim3 <- sfcr_multis(mlt_sim1, fixed = shock1, periods = 50)
```


## Plotting the results

To visualize the results, the user must combine all the models in a single `tibble` using the `bind_rows()` function from `dplyr`, or using `rbind` from `base`. From there, the usual strategy of reshaping the `tibble` into long format and plotting with `ggplot2` should be applied.

Below I present a simplified example:

```{r, fig.height=9, fig.width=7}
mlt_sim1 %>%
  bind_rows() %>%
  pivot_longer(cols = -c(period, simulation)) %>%
  filter(name %in% c("Y", "YD", "Cd")) %>%
  ggplot(aes(x = period, y = value)) +
  geom_line(aes(color = as_factor(simulation))) +
  facet_wrap(~name, nrow = 3) +
  scale_color_hue("alpha1",
                  labels = as.character(seq(0.5, 0.9, 0.02))) +
  theme(legend.position = "bottom")

```

As can be seen in this example, the `alpha1` parameter affects how fast the model arrives to the steady state but does not change the steady state itself.