# Package Outline

## 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 that focus on specific models.

### 1. Model creation

Use the `create_model()` function to initialize an SFC model (SFC object):

    library(godley)
    model_sim <- create_model(name = "SFC model")
    #> Empty model created

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:

    # 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.

    # 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:

    # Change initial value for alpha1 parameter
    model_sim <- change_init(model = model_sim, name = "alpha1", value = 0.5)
    #> Changed alpha1 initial value to 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:

    # 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"
    )
    #> Model prepared successfully
    #> Simulating scenario baseline (1 of 1)
    #> Scenario(s) successfully simulated

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:

    # 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.

    # 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()`:

    # Create shock
    sim_shock <- create_shock()
    #> Shock object created

### 2. Adding shock equations

Use `add_shock()` to define the shock equations:

    # 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()`:

    # 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:

    # 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"
    )
    #> Simulating scenario expansion (1 of 1)
    #> Scenario(s) successfully simulated

## 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()`:

    # Create and calculate sensitivity
    model_sen <- create_sensitivity(
      model_pass = model_sim, variable = "alpha1",
      lower = 0.1, upper = 0.8, step = 0.1
    )
    #> Model loaded from environment
    #> Model prepared successfully

    model_sen <- simulate_scenario(
      model = model_sen, max_iter = 350, periods = 100, hidden_tol = 0.1,
      tol = 1e-08, method = "Gauss"
    )
    #> Simulating scenario baseline (1 of 9)
    #> Simulating scenario sensitivity_alpha1_0.1 (2 of 9)
    #> Simulating scenario sensitivity_alpha1_0.2 (3 of 9)
    #> Simulating scenario sensitivity_alpha1_0.3 (4 of 9)
    #> Simulating scenario sensitivity_alpha1_0.4 (5 of 9)
    #> Simulating scenario sensitivity_alpha1_0.5 (6 of 9)
    #> Simulating scenario sensitivity_alpha1_0.6 (7 of 9)
    #> Simulating scenario sensitivity_alpha1_0.7 (8 of 9)
    #> Simulating scenario sensitivity_alpha1_0.8 (9 of 9)
    #> Scenario(s) successfully simulated

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).