/readsdr

Translate System Dynamics models (Stella, Vensim) into R

Primary LanguageROtherNOASSERTION

readsdr

Codecov test coverage CRAN status R-CMD-check

Overview

The goal of readsdr is to bridge the design capabilities from specialised System Dynamics software with the powerful numerical tools offered by R libraries. The package accomplishes this goal by parsing .xmile files (Vensim and Stella models) into R objects to construct networks (graph theory), ODE functions for deSolve and Stan.

Installation

You can install the released version of readsdr from CRAN with:

install.packages("readsdr")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("jandraor/readsdr")

Usage

library(readsdr)
filepath <- system.file("models/", "SIR.stmx", package = "readsdr")
mdl      <- read_xmile(filepath)

Vensim models can only be read if they are exported in the .xmile format. Sometimes, Vensim .xmile files can be problematic, where some stocks may not have flows, and flow equations are put as initial values. One way to address this issue is by copying the .mdl file to a different folder and exporting the .xmile file again. If you encounter this issue, please let the developers know at Vensim’s forum.

Tutorials

For information on how to use this package, please check:

Supported builtins

  • Stella
    • Comparison operators (=, <>)
    • Logical operators (AND, OR, NOT)
    • If Else Then
    • Inequality operators (<, >)
    • Pulse 1
    • Step 1
    • Endogenous table functions
    • Smoothing functions2: SMTH1, SMTH3, SMTHN
    • Delay functions: DELAYN
    • Limited support to uni-dimensional arrays. Apply all translation is restricted to numeric values.
    • Math functions: ABS, EXP, SQRT
    • Stats functions: NORMAL3
  • Vensim
    • Comparison operators (=, <>)
    • Logical operators (:AND:, :OR:, :NOT:)
    • IF_THEN_ELSE
    • Inequality operators (<, >)
    • Pulse 1
    • Pulse Train 1
    • Step 1
    • Endogenous table functions
    • Smoothing functions2: SMOOTH, SMOOTH3, SMOOTH3I, SMOOTHI
    • Delay functions: DELAY N
    • Math functions: ABS, EXP, SQRT
    • Limited support to bi-dimensional arrays.
    • Stats functions: RANDOM NORMAL3

1 Restricted to Euler integration.

2 These functions cannot be part of more complex mathematical expressions. That is, the auxiliary variable must only contain one smoothing function and nothing else.

3 Seed is ignored.

Notes

  • uniflow and non-negative stock features from Stella are not supported.

  • No built-in is supported for translations to Stan code.

  • Modules from Stella are not supported.

Applications

This package has been instrumental in the following works:

  • Andrade et al (2024). Preparing for pandemic response in the context of limited resources. System Dynamics Review.

  • Andrade & Duggan (2023). Anchoring the mean generation time in the SEIR to mitigate biases in $\Re_0$ estimates due to uncertainty in the distribution of the epidemiological delays. Royal Society Open Science.

  • Andrade & Duggan (2022). Inferring the effective reproductive number from deterministic and semi-deterministic compartmental models using incidence and mobility data. PLOS Computational Biology.

  • Andrade & Duggan (2021). A Bayesian approach to calibrate system dynamics models using Hamiltonian Monte Carlo. System Dynamics Review.

  • Andrade & Duggan (2020). An evaluation of Hamiltonian Monte Carlo performance to calibrate age-structured compartmental SEIR models to incidence data. Epidemics.

Acknowledgments

Thanks to:

  • Rogelio Oliva for advocating the need to create an open-source tool for the System Dynamics community and push forward this endeavour.
  • Sergey Naumov for his ideas to implement several functions in this package.
  • Jim Duggan from whom I borrowed ideas to implement this package.

References

Duggan, J. (2016). System Dynamics Modeling with R. Springer.