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

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

## Scenario simulation

The objective of this vignette is to walk through a few steps needed to create and simulate a baseline scenario. To explore all the possibilities for simulating various	models with Godley, please refer to other, more detailed articles on [this website](https://gamrot.github.io/godley/) that focus on specific models.

### 1. Model creation
Use the `create_model()` function to initialize an SFC model (SFC object):

```{r}
library(godley)
model_sim <- create_model(name = "SFC model")
```

**Arguments:**  

- `name`: Model name (required).  
- `template`: Name of a model template to upload (optional).  

*Note:* Users can skip manually adding variables and equations (steps 2 and 3 below) by uploading model attributes from pre-defined templates included in the package. Available templates include: `SIM`, `SIMEX`, `PC`, `LP`, `REG`, `OPEN`, `BMW`, `BMWK`, `DIS`, and `DISINF`.


### 2. Adding variables
Add variables to the model using the `add_variable()` function. It incorporates variables by creating new entries in the SFC tibble:

```{r}
# Add parameters
model_sim <- add_variable(model = model_sim, name = "C_d", desc = "Consumption demand by households")
model_sim <- add_variable(model = model_sim, name = "C_s", desc = "Consumption supply")
model_sim <- add_variable(model = model_sim, name = "G_s", desc = "Government supply")
model_sim <- add_variable(model = model_sim, name = "H_h", desc = "Cash money held by households")
model_sim <- add_variable(
  model = model_sim, name = "H_s",
  desc = "Cash money supplied by the government"
)
model_sim <- add_variable(model = model_sim, name = "N_d", desc = "Demand for labor")
model_sim <- add_variable(model = model_sim, name = "N_s", desc = "Supply of labor")
model_sim <- add_variable(model = model_sim, name = "T_d", desc = "Taxes, demand")
model_sim <- add_variable(model = model_sim, name = "T_s", desc = "Taxes, supply")
model_sim <- add_variable(model = model_sim, name = "Y", desc = "Income = GDP")
model_sim <- add_variable(model = model_sim, name = "Yd", desc = "Disposable income of households")
model_sim <- add_variable(
  model = model_sim, name = "alpha1", init = 0.6,
  desc = "Propensity to consume out of income"
)
model_sim <- add_variable(
  model = model_sim, name = "alpha2", init = 0.4,
  desc = "Propensity to consume out of wealth"
)
model_sim <- add_variable(model = model_sim, name = "theta", init = 0.2, desc = "Tax rate")
model_sim <- add_variable(model = model_sim, name = "G_d", init = 20, desc = "Government demand")
model_sim <- add_variable(model = model_sim, name = "W", init = 1, desc = "Wage rate")
```

**Arguments:**  

- `model`: The name of the model (required).  
- `name`: The name of the variable (required).  
- `init`: The initial value of the variable (optional).  
- `desc`: A description of the variable (optional).  


### 3. Adding equations
Add equations to the SFC model using the `add_equation()` function. This also creates new entries in the SFC tibble.

```{r}
# Add equations
model_sim <- add_equation(model = model_sim, equation = "C_s = C_d", desc = "Consumption")
model_sim <- add_equation(model = model_sim, equation = "G_s = G_d")
model_sim <- add_equation(model = model_sim, equation = "T_s = T_d")
model_sim <- add_equation(model = model_sim, equation = "N_s = N_d")
model_sim <- add_equation(model = model_sim, equation = "Yd = W * N_s - T_s")
model_sim <- add_equation(model = model_sim, equation = "T_d = theta * W * N_s")
model_sim <- add_equation(model = model_sim, equation = "C_d = alpha1 * Yd + alpha2 * H_h[-1]")
model_sim <- add_equation(model = model_sim, equation = "H_s = G_d - T_d + H_s[-1]")
model_sim <- add_equation(model = model_sim, equation = "H_h = Yd - C_d + H_h[-1]")
model_sim <- add_equation(model = model_sim, equation = "Y = C_s + G_s")
model_sim <- add_equation(model = model_sim, equation = "N_d = Y/W")
model_sim <- add_equation(
  model = model_sim, equation = "H_s = H_h", desc = "Money equilibrium",
  hidden = TRUE
)
```

**Arguments:**  

- `model`: The name of the model (required).  
- `equation`: The formula for the equation (required).  
- `desc`: A description of the equation (optional).  
- `hidden`: A boolean indicating whether the equation should be hidden (optional). Hidden equations are excluded from simulation.  


### 4. Altering initial values (optional)
If you want to modify the initial values of parameters, simply apply the `change_init()` function:

```{r}
# Change initial value for alpha1 parameter
model_sim <- change_init(model = model_sim, name = "alpha1", value = 0.5)
```

**Arguments:**  

- `model`: The name of the model (required).  
- `name`: The name of the parameter (required).  
- `value`: The new initial value for the parameter (required).  


### 5. Simulating scenario(s)
Now, you can simulate the specified scenarios by running the `simulate_scenario()` function:

```{r}
# Simulate baseline scenario
model_sim <- simulate_scenario(
  model = model_sim, scenario = "baseline", max_iter = 350, periods = 100,
  hidden_tol = 0.1, tol = 1e-08, method = "Gauss"
)
```

**Arguments:**  

- `model`: The name of the SFC model (required).  
- `scenario`: The name of the scenario to be simulated (optional).  
- `max_iter`: The maximum number of iterations for the simulation (optional).  
- `periods`: The number of simulation periods (optional).  
- `hidden_tol`: The maximum allowable error for hidden equations (optional).  
- `tol`: The maximum allowable error for the algorithm to converge during the simulation (optional).  
- `method`: The calculation method to be used (`'Newton'` or `'Gauss'`) (optional).  

*Note*: If scenario name is not provided all not simulated scenarios will be calculated.


## Model — plots
Finally, to visualize the model simulation, use the `plot_simulation()` function:

```{r, out.width="100%"}
# Plot results
plot_simulation(
  model = model_sim, scenario = "baseline", from = 1, to = 100,
  expressions = c("Y", "C_s / alpha1")
)
```

**Arguments:**  

- `model`: The name of the SFC model to be displayed on the chart (required).  
- `scenario`: The name of the scenario(s) to include on the chart (optional).  
- `take_all`: A boolean indicating whether all scenarios containing the specified scenario name strings should be displayed on the chart (optional).  
- `from`: The starting period to be displayed on the chart (optional).  
- `to`: The ending period to be displayed on the chart (optional).  
- `expressions`: The variable names or equations to visualize on the chart (optional).  

For a broader view of the model's structure, use `plot_cycles()` to see how variables are interconnected. It helps you see how the variables are interconnected and may reveal any loops, like feedback mechanisms or endogeneity.

```{r, out.width="100%"}
# Plot relationships
plot_cycles(model = model_sim)
```

**Arguments:**  

- `model`: The SFC model object generated using the `create_model()` function.  
- `save_file`: The file name and path where the plot will be saved as an HTML file.

## Model — simulating shock(s)
Beyond the baseline scenario, you can explore how market disruptions affect the economy. To simulate a shock scenario, follow these steps:

### 1. Creating shock object
Initialize a SFC shock tibble object using `create_shock()`:

```{r}
# Create shock
sim_shock <- create_shock()
```

### 2. Adding shock equations
Use `add_shock()` to define the shock equations:

```{r}
# Add shock equation for increased government expenditures
sim_shock <- add_shock(
  shock = sim_shock,
  variable = "G_d",
  value = 25,
  desc = "Increase in government expenditures", start = 5, end = 10
)
```

**Arguments:**

- `shock`: The name of the shock object where the new equation will be added (required).  
- `equation`: The (new) equation describing the applied shock (required).  
- `desc`: A description of the applied shock (optional).  
- `start`: The initial period when the shock will be applied (optional).  
- `end`: The final period during which the shock will be applied (optional).

*Note*: 'start' and 'end' parameters are set by default to NA, so by default the shock will be applied to the whole simulation period

### 3. Adding shock scenario to the SFC model
Integrate the shock into your model using `add_scenario()`:

```{r}
# Add shock scenario for increased government expenditures
model_sim <- add_scenario(
  model = model_sim, name = "expansion", origin = "baseline",
  origin_start = 1,
  origin_end = 100,
  shock = sim_shock
)
```

**Arguments:**  

- `model`: The name of the model to which the new scenario will be added (required).  
- `name`: The name of the new scenario (optional).  
- `origin`: The name of the baseline scenario to use as a reference (optional).  
- `origin_start`: The period from the baseline scenario to be used as the initial period in the new scenario (optional).
- `origin_end`: The period from the baseline scenario to be used as the final period in the new scenario (optional).  
- `shock`: The name of the created SFC shock object to be applied (required).  

### 4. Simulating shock scenario
Run the simulation for the shock scenario:

```{r}
# Calculate shock scenario for increased government expenditures
model_sim <- simulate_scenario(
  model = model_sim, max_iter = 350, periods = 100, hidden_tol = 0.1,
  tol = 1e-08, method = "Gauss"
)
```

## Model — sensitivity analysis
For a more comprehensive view, you can carry out sensitivity analysis. Sensitivity analysis allows the creation of multiple scenarios in a separate SFC model by modifying the initial value of a selected variable. To perform sensitivity analysis, use `create_sensitivity()` and `simulate_scenario()`:
 
```{r}
# Create and calculate sensitivity
model_sen <- create_sensitivity(
  model_pass = model_sim, variable = "alpha1",
  lower = 0.1, upper = 0.8, step = 0.1
)

model_sen <- simulate_scenario(
  model = model_sen, max_iter = 350, periods = 100, hidden_tol = 0.1,
  tol = 1e-08, method = "Gauss"
)
```

**Arguments:**  

- `model_pass`: The name of the SFC model or scenario template to be used for the sensitivity calculation (required).  
- `variable`: The name of the variable to be analyzed in the sensitivity calculation (required).  
- `lower`: The minimum value of the variable for the sensitivity calculation (optional).  
- `upper`: The maximum value of the variable for the sensitivity calculation (optional).  
- `step`: The increment by which the variable will change during the sensitivity analysis (optional).