README (original) (raw)

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 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, 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, 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 notsupported.

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.