readsdr

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) 

For reading Vensim models, they must be exported as .xmile.

Tutorials

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

• Basics

• Inference

Supported builtins

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

¹ Restricted to Euler integration.

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

³ 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 & 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.