-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.Rmd
148 lines (105 loc) · 5.35 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# readsdr
<!-- badges: start -->
[](https://app.codecov.io/gh/jandraor/readsdr?branch=master)
[](https://CRAN.R-project.org/package=readsdr)
[](https://github.com/jandraor/readsdr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
## 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](https://www.iseesystems.com/) models) into R objects to
construct [networks](https://igraph.org) (graph theory), ODE functions for
[deSolve](http://desolve.r-forge.r-project.org/) and
[Stan](https://mc-stan.org/).
## Installation
You can install the released version of readsdr from [CRAN](https://CRAN.R-project.org) with:
``` r
install.packages("readsdr")
```
And the development version from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("jandraor/readsdr")
```
## Usage
```{r example}
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](https://www.ventanasystems.co.uk/forum).
## Tutorials
For information on how to use this package, please check:
* [Basics](https://jandraor.github.io/tutorials/Basics.html)
* [Inference](https://jandraor.github.io/tutorials/Inference.html)
## Supported builtins
* **Stella**
+ Comparison operators (`=`, `<>`)
+ Logical operators (`AND`, `OR`, `NOT`)
+ `If Else Then`
+ Inequality operators (`<`, `>`)
+ `Pulse` ^1^
+ `Step` ^1^
+ Endogenous table functions
+ Smoothing functions^2^: `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: `NORMAL`^3^
* **Vensim**
+ Comparison operators (`=`, `<>`)
+ Logical operators (`:AND:`, `:OR:`, `:NOT:`)
+ `IF_THEN_ELSE`
+ Inequality operators (`<`, `>`)
+ `Pulse` ^1^
+ `Pulse Train` ^1^
+ `Step` ^1^
+ Endogenous table functions
+ Smoothing functions^2^: `SMOOTH`, `SMOOTH3`, `SMOOTH3I`, `SMOOTHI`
+ Delay functions: `DELAY N`
+ Math functions: `ABS`, `EXP`, `SQRT`
+ Limited support to *bi-dimensional* arrays.
+ Stats functions: `RANDOM NORMAL`^3^
^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)](https://doi.org/10.1002/sdr.1775). _Preparing for pandemic response in the context of limited resources_. **System Dynamics Review**.
* [Andrade & Duggan (2023)](https://doi.org/10.1098/rsos.230515). _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)](https://doi.org/10.1371/journal.pcbi.1010206). _Inferring the effective reproductive number from deterministic and semi-deterministic compartmental models using incidence and mobility data_. **PLOS Computational Biology**.
* [Andrade & Duggan (2021)](https://doi.org/10.1002/sdr.1693). _A Bayesian approach to calibrate system dynamics models using Hamiltonian Monte Carlo_. **System Dynamics Review**.
* [Andrade & Duggan (2020)](https://doi.org/10.1016/j.epidem.2020.100415). _An evaluation of Hamiltonian Monte Carlo performance to calibrate age-structured compartmental SEIR models to incidence data_. **Epidemics**.
## Acknowledgments
Thanks to:
* [Rogelio Oliva](http://people.tamu.edu/~roliva/) 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](https://github.com/JimDuggan)
from whom I borrowed ideas to implement this package.
## References
[Duggan, J. (2016). *System Dynamics Modeling with R*. Springer.](https://link.springer.com/book/10.1007/978-3-319-34043-2)