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