Type: Package
Title: Stock-Flow-Consistent Model Simulator
Version: 0.2.2
Maintainer: Elżbieta Jowik <jowik.elzbieta@gmail.com>
Description: Define, simulate, and validate stock-flow consistent (SFC) macroeconomic models. The godley R package offers tools to dynamically define model structures by adding variables and specifying governing systems of equations. With it, users can analyze how different macroeconomic structures affect key variables, perform parameter sensitivity analyses, introduce policy shocks, and visualize resulting economic scenarios. The accounting structure of SFC models follows the approach outlined in the seminal study by Godley and Lavoie (2007, ISBN:978-1-137-08599-3), ensuring a comprehensive integration of all economic flows and stocks. The algorithms implemented to solve the models are based on methodologies from Kinsella and O'Shea (2010) <doi:10.2139/ssrn.1729205>, Peressini and Sullivan (1988, ISBN:0-387-96614-5), and contributions by Joao Macalos.
URL: https://gamrot.github.io/godley/
BugReports: https://github.com/gamrot/godley/issues
License: GPL (≥ 3)
Encoding: UTF-8
Imports: dplyr, stringr, tidyr, igraph, purrr, vctrs, rlang, rootSolve, plotly, magrittr, checkmate, vecsets, lubridate, data.table, tibble, visNetwork
Depends: R (≥ 4.1.0)
RoxygenNote: 7.3.2
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-02-22 08:21:18 UTC; ejowik001
Author: Michał Gamrot [aut, cph], Iwo Augustyński [ctb], Julian Kacprzak [ctb], Elżbieta Jowik [cre, ctb]
Repository: CRAN
Date/Publication: 2025-02-23 23:30:06 UTC

Add equations to the model

Description

Add equations to the model

Usage

add_equation(model, ...)

Arguments

model

SFC model object

...

additional arguments passed to the function.

Value

updated SFC model object containing added equation

Add single equation to the model

Description

helper for add_equation()

Usage

add_equation_single(model, equation, hidden = FALSE, desc = "")

Arguments

model

SFC model object

equation

string equation in format: 'x = y + z - a * b + (c + d) / e + f[-1]'

hidden

logical, indicates if equation should be written as hidden, defaults to FALSE

desc

string equation description

Add scenario to the model

Description

Add scenario to the model

Usage

add_scenario(
  model,
  name = "expansion",
  origin = "baseline",
  origin_start = NA,
  origin_end = NA,
  shock
)

Arguments

model

SFC model object

name

string name of scenario, defaults to 'expansion'

origin

string name of origin scenario, from which the new scenario will be created, defaults to 'baseline'

origin_start

numeric period number from origin scenario from which the new scenario will begin

origin_end

numeric period number from origin scenario on which the new scenario will end

shock

shock object from create_shock() and add_shock()

Value

updated SFC model object containing added scenario

Add shock to shock object

Description

Add shock to shock object

Usage

add_shock(
  shock,
  variable,
  value = NA,
  rate = NA,
  absolute = NA,
  start = NA,
  end = NA,
  desc = ""
)

Arguments

shock

tibble from create_shock()

variable

string variable name

value

numeric, an explicit value or values for the variable, will be extended with last value

rate

numeric, multiplier to influence the original value of the variable

absolute

numeric, absolute value to influence the original value of the variable

start

numeric or date period number for the shock to take place, defaults to NA

end

numeric or date period number for the shock to take place, defaults to NA

desc

string variable description

Value

updated shock object containing added shock

Add variables to the model

Description

Add variables to the model

Usage

add_variable(model, ...)

Arguments

model

SFC model object

...

additional arguments passed to the function.

Value

updated SFC model object containing added variable

Add single variable to the model

Description

helper for add_variable()

Usage

add_variable_single(model, name, init = NA, desc = "")

Arguments

model

SFC model object

name

string name for added variable

init

numeric initial value, defaults to 1e-05

desc

string variable description

Change initial value of a variable

Description

Change initial value of a variable

Usage

change_init(model, name, value)

Arguments

model

SFC model object

name

string variable name

value

numeric value that will replace existing initial value

Value

updated SFC model object with new variable initial value

Verify if parentheses in the equation are properly balanced

Description

This function checks if all parentheses in a given equation string are correctly paired and balanced. If there are no parentheses, the equation is considered trivially balanced. It returns 'TRUE' if the parentheses are balanced and 'FALSE' otherwise.

Usage

check_parentheses_balance(eq)

Arguments

eq

A character string representing an equation.

Value

A logical value indicating whether the parentheses are balanced ('TRUE') or not ('FALSE').

Create SFC model object

Description

Create SFC model object

Usage

create_model(name = "SFC model", template)

Arguments

name

string name for created SFC model object

template

string name of model template chosen from: 'SIM', 'PC', 'LP', 'REG', 'OPEN', 'BMW', 'BMWK', 'DIS', 'DISINF', 'SIMEX', 'PCEX' or user created SFC model object to be used as a template

Value

SFC model object

Create model with sensitivity scenarios

Description

Create model with sensitivity scenarios

Usage

create_sensitivity(model_pass, variable, lower = 0, upper = 1, step = 0.1)

Arguments

model_pass

SFC model object that will be used as a baseline for sensitivity calculation

variable

string name of the variable that will be used

lower

numeric lower bound value of the variable

upper

numeric upper bound value of the variable

step

numeric step between upper and lower bounds for the variable to take value

Value

SFC model object with sensitivity scenarios

Create shock used in add_scenario().

Description

Create shock used in add_scenario().

Usage

create_shock()

Value

shock object

Calculate 1 order lag difference of a variable in model

Description

Calculate 1 order lag difference of a variable in model

Usage

d(x)

Arguments

x

variable name

Details

this is a special function to be used exclusively in model equation strings e.g. "x = d(y) + z"

Value

difference

Network plot of the model

Description

Network plot of the model

Usage

plot_cycles(model, save_file = NULL)

Arguments

model

SFC model object created with create_model

save_file

name and path to save the plot as html file

Details

This function creates a representation of a model as a directed graph. Additionally it shows cycles in the model including these with lagged variables. Graph can be saved as html file.

Value

visNetwork object

Examples

model <- godley::create_model(name = "SFC model", template = "BMW")
plot_cycles(model)

Plot simulations of multiple variables in multiple scenarios

Description

Plot simulations of multiple variables in multiple scenarios

Usage

plot_simulation(
  model,
  scenario = "baseline",
  take_all = FALSE,
  from = NA,
  to = NA,
  expressions = "Y"
)

Arguments

model

SFC model object

scenario

vector of strings or single string name of scenario(s) from which take variables values, defaults to 'baseline'

take_all

logical indicating whether all scenarios containing the given scenario name string(s) should be used, defaults to FALSE

from

numeric period number from which the plot should start, defaults to maximum value

to

numeric period number on which the plot should end, defaults to minimum value

expressions

vector of strings or single string name of variable(s) expression(s) to plot, defaults to 'Y'

Value

plotly plot

Make initial matrix row for baseline scenario and prepare equations for simulate_scenario()

Description

Make initial matrix row for baseline scenario and prepare equations for simulate_scenario()

Usage

prepare(model, verbose = FALSE)

Arguments

model

SFC model object

verbose

logical to tell if additional model verbose should be displayed

Value

verified and prepared SFC model object

Restore equation notation for warning messages

Description

This function converts an internally processed equation expression (e.g., ‘m[.i, ’Var']') into a more readable format (e.g., 'Var'). The function handles lagged variables, transforming expressions such as ‘m[.i - 1, ’Var']' into 'Var[-1]'. It is intended for use in warning messages.

Usage

restore_equation(eq_line)

Arguments

eq_line

A character string representing an equation with internal indexing.

Value

A character string where the internal indexing notation has been restored to a more user-friendly form.

Simulate scenario of SFC model object

Description

Simulate scenario of SFC model object

Usage

simulate_scenario(
  model,
  scenario,
  periods = NA,
  start_date = NA,
  method = "Gauss",
  max_iter = 350,
  tol = 1e-05,
  hidden_tol = 0.1,
  verbose = FALSE
)

Arguments

model

SFC model object

scenario

vector of strings or single string name of scenario(s) to simulate

periods

numeric total number of rows (periods) in the model, defaults to 100

start_date

character date to begin the simulation in the format "yyyy-mm-dd"

method

string name of method used to find solution chosen from: 'Gauss', 'Newton', defaults to 'Gauss'

max_iter

numeric maximum iterations allowed per period, defaults to 350

tol

numeric tolerance accepted to determine convergence, defaults to 1e-05

hidden_tol

numeric error tolerance to accept the equality of hidden equations, defaults to 0.1.

verbose

logical to tell if additional model verbose should be displayed

Value

updated model containing simulated scenario(s)