epidsl 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- epidsl-0.1.0/LICENSE +21 -0
- epidsl-0.1.0/PKG-INFO +665 -0
- epidsl-0.1.0/README.md +636 -0
- epidsl-0.1.0/pyproject.toml +82 -0
- epidsl-0.1.0/pyproject.toml.orig +67 -0
- epidsl-0.1.0/src/epidsl/__init__.py +18 -0
- epidsl-0.1.0/src/epidsl/backends/__init__.py +167 -0
- epidsl-0.1.0/src/epidsl/backends/_stochastic.py +232 -0
- epidsl-0.1.0/src/epidsl/backends/gillespie.py +125 -0
- epidsl-0.1.0/src/epidsl/backends/ode.py +77 -0
- epidsl-0.1.0/src/epidsl/backends/tau_leap.py +203 -0
- epidsl-0.1.0/src/epidsl/calibration.py +429 -0
- epidsl-0.1.0/src/epidsl/checks.py +205 -0
- epidsl-0.1.0/src/epidsl/cli.py +367 -0
- epidsl-0.1.0/src/epidsl/compose.py +694 -0
- epidsl-0.1.0/src/epidsl/ensemble.py +77 -0
- epidsl-0.1.0/src/epidsl/errors.py +23 -0
- epidsl-0.1.0/src/epidsl/expr.py +141 -0
- epidsl-0.1.0/src/epidsl/grammar.lark +72 -0
- epidsl-0.1.0/src/epidsl/ir.py +318 -0
- epidsl-0.1.0/src/epidsl/lsp.py +205 -0
- epidsl-0.1.0/src/epidsl/parallel.py +86 -0
- epidsl-0.1.0/src/epidsl/parser.py +321 -0
- epidsl-0.1.0/src/epidsl/py.typed +0 -0
- epidsl-0.1.0/src/epidsl/studio/__init__.py +1 -0
- epidsl-0.1.0/src/epidsl/studio/api.py +320 -0
- epidsl-0.1.0/src/epidsl/studio/server.py +145 -0
- epidsl-0.1.0/src/epidsl/studio/static/app.js +740 -0
- epidsl-0.1.0/src/epidsl/studio/static/index.html +84 -0
- epidsl-0.1.0/src/epidsl/studio/static/style.css +363 -0
epidsl-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 A. Yvan Guifo Fodjo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
epidsl-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,665 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: epidsl
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A domain-specific language for compositional epidemiological modelling
|
|
5
|
+
Keywords: epidemiology,modelling,dsl,compartmental models,simulation,calibration
|
|
6
|
+
Author: Yvan Guifo
|
|
7
|
+
Author-email: Yvan Guifo <yvanguifo@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Dist: lark>=1.3.1
|
|
21
|
+
Requires-Dist: numpy>=2.0
|
|
22
|
+
Requires-Dist: pygls>=2.1.1
|
|
23
|
+
Requires-Dist: scipy>=1.13
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Project-URL: Homepage, https://github.com/YvanGuifo/epidsl
|
|
26
|
+
Project-URL: Repository, https://github.com/YvanGuifo/epidsl
|
|
27
|
+
Project-URL: Issues, https://github.com/YvanGuifo/epidsl/issues
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# EpiDSL
|
|
31
|
+
|
|
32
|
+
A domain-specific language for epidemiological modelling. A model is written once as
|
|
33
|
+
compartments and flows, checked statically, and compiled to a typed intermediate
|
|
34
|
+
representation that simulation backends consume.
|
|
35
|
+
|
|
36
|
+
**Status:** early development. Deterministic (ODE) and stochastic (Gillespie,
|
|
37
|
+
tau-leap) simulation, model composition, calibration and a visual workbench work
|
|
38
|
+
end to end (see [Roadmap](#roadmap)).
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
EpiDSL is not published on PyPI yet. Work from a checkout: it requires Python 3.11
|
|
43
|
+
or later and [uv](https://docs.astral.sh/uv/).
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
uv sync
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Supported and tested: Python 3.11 to 3.14, NumPy 2.0 or later, SciPy 1.13 or later.
|
|
50
|
+
|
|
51
|
+
## Write a model
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
model SIR {
|
|
55
|
+
semantics: [ODE]
|
|
56
|
+
|
|
57
|
+
compartment S = 990, I = 10, R = 0
|
|
58
|
+
|
|
59
|
+
parameter beta = 0.3 [1/day] -- transmission rate
|
|
60
|
+
rate gamma = 0.1 [1/day] -- recovery rate
|
|
61
|
+
|
|
62
|
+
flow S -> I : beta * S * I / N
|
|
63
|
+
flow I -> R : gamma * I
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Check and run it
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
uv run epidsl check examples/sir.epidsl
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
uv run epidsl run examples/sir.epidsl --t-end 160 --out sir.csv
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`run` writes one CSV row per output time, with a column `t` and one column per
|
|
78
|
+
compartment. Without `--out` the CSV goes to standard output.
|
|
79
|
+
|
|
80
|
+
## Open the studio
|
|
81
|
+
|
|
82
|
+
The studio shows a model, its simulations and its calibration in the browser. The
|
|
83
|
+
text file stays the model: the studio reads it, checks it as you type, and saves it
|
|
84
|
+
back.
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
uv run epidsl studio examples/sir_age_structured.epidsl
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
It prints a local address and opens it. Stop it with Ctrl+C. Started without a
|
|
91
|
+
file, it opens a small template that cannot be saved.
|
|
92
|
+
|
|
93
|
+
- **Source.** Edit the model on the left. Lines with a problem are marked, and the
|
|
94
|
+
list below explains each one; click an entry to jump to its line.
|
|
95
|
+
- **Model.** Compartments are laid out as a grid. For a composed model the first
|
|
96
|
+
model gives the columns and the others the rows, so each cell is one combination
|
|
97
|
+
of states. Arrows are the flows, coloured by the model they come from; a dashed
|
|
98
|
+
arrow is a synchronised transition. Select an arrow to read its rate and to
|
|
99
|
+
highlight the line of source that produced it. One line can produce several
|
|
100
|
+
arrows: that is composition made visible.
|
|
101
|
+
- **Simulation.** Choose a method the model declares, then **Run** (Ctrl+Enter).
|
|
102
|
+
ODE runs again by itself as you edit. With a stochastic method and several runs,
|
|
103
|
+
the chart shows the mean and a 95% band. Click a name under the chart to show or
|
|
104
|
+
hide it; observables are dashed and hidden at first.
|
|
105
|
+
- **Calibration.** Paste or load the observations, then **Calibrate**. Each
|
|
106
|
+
parameter is shown on a track that spans its prior, with its 95% interval and
|
|
107
|
+
median, and the chart shows the model at the estimated values with the data.
|
|
108
|
+
|
|
109
|
+
The studio listens on this computer only, loads nothing from the internet, and
|
|
110
|
+
answers only its own page. It uses port 8642, or a free one if that is taken;
|
|
111
|
+
`--port` chooses one and `--no-browser` does not open the browser.
|
|
112
|
+
|
|
113
|
+
## Use your editor with the language server
|
|
114
|
+
|
|
115
|
+
`epidsl server` starts a Language Server Protocol server over stdio. Any
|
|
116
|
+
editor with LSP support (VS Code, Neovim, Emacs, Helix, …) can use it to get:
|
|
117
|
+
|
|
118
|
+
- **Diagnostics in real time** — all static checks (C1–C13) run on every save and
|
|
119
|
+
the results appear as squiggles or a problem list.
|
|
120
|
+
- **Completion** — keywords, math functions, and every compartment and constant
|
|
121
|
+
declared in the file.
|
|
122
|
+
- **Goto definition** — jump to where a compartment, rate, parameter or observable
|
|
123
|
+
is declared.
|
|
124
|
+
|
|
125
|
+
Configure your editor to run `epidsl server` as a language server for files
|
|
126
|
+
with extension `.epidsl`. For VS Code, add a launch entry like this in
|
|
127
|
+
`.vscode/settings.json`:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"languageServerExample.trace.server": "verbose",
|
|
132
|
+
"[epidsl]": {
|
|
133
|
+
"editor.defaultFormatter": null
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
For Neovim with `nvim-lspconfig`, register it as a custom server:
|
|
139
|
+
|
|
140
|
+
```lua
|
|
141
|
+
vim.api.nvim_create_autocmd("FileType", {
|
|
142
|
+
pattern = "epidsl",
|
|
143
|
+
callback = function()
|
|
144
|
+
vim.lsp.start({
|
|
145
|
+
name = "epidsl",
|
|
146
|
+
cmd = { "epidsl", "server" },
|
|
147
|
+
root_dir = vim.fn.getcwd(),
|
|
148
|
+
})
|
|
149
|
+
end,
|
|
150
|
+
})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Run a stochastic simulation
|
|
154
|
+
|
|
155
|
+
Two methods simulate one random trajectory of whole individuals. The model must
|
|
156
|
+
list the method in its `semantics` (`Gillespie` or `TauLeap`).
|
|
157
|
+
|
|
158
|
+
| Method | What it does | Use it when |
|
|
159
|
+
|--------|--------------|-------------|
|
|
160
|
+
| `--method gillespie` | Exact: fires one individual event at a time. | The population is small, or you need the exact law. |
|
|
161
|
+
| `--method tau-leap` | Approximate: fires many events per time step. | The population is large and exact simulation is too slow. |
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
uv run epidsl run examples/sir.epidsl --t-end 160 --method gillespie --seed 1
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`--seed` makes the run reproducible; without it each run differs.
|
|
168
|
+
|
|
169
|
+
To summarise many runs, add `--runs`. The CSV then holds, for each compartment, the
|
|
170
|
+
mean over the runs and the quantiles given by `--quantiles` (by default 0.025 and
|
|
171
|
+
0.975, a 95% band), in columns such as `I_mean`, `I_q0.025` and `I_q0.975`:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
uv run epidsl run examples/sir.epidsl --t-end 160 --method gillespie --runs 200 --seed 1
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
With `--runs`, `--seed` fixes the whole set of runs. `--runs` is refused with the
|
|
178
|
+
ODE method, which always gives the same trajectory.
|
|
179
|
+
|
|
180
|
+
Both methods require whole-number initial values. A flow never fires from an empty
|
|
181
|
+
compartment, and a rate that evaluates to a negative number stops the run with an
|
|
182
|
+
error.
|
|
183
|
+
|
|
184
|
+
A rate may use `t`, for a season or a dated change:
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
flow S -> I : beta * (1 + swing * cos(6.283185307 * t / year)) * S * I / N
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
uv run epidsl run examples/sir_seasonal.epidsl --t-end 730 --method tau-leap --seed 1
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Gillespie stays exact with such a rate, by integrating it to find each waiting time,
|
|
195
|
+
but that costs far more per event: on the example above, 11 seconds for 30 000
|
|
196
|
+
events against 0.15 seconds for the same model without a season. Tau-leap handles it
|
|
197
|
+
at its usual speed (0.15 seconds here) and is the practical choice beyond a few
|
|
198
|
+
thousand individuals.
|
|
199
|
+
|
|
200
|
+
Tau-leap chooses its own step sizes, following Cao, Gillespie and Petzold (2006),
|
|
201
|
+
and switches to exact steps while few individuals are involved. Its error shrinks with its accuracy parameter `epsilon`
|
|
202
|
+
(default 0.03, set with `--epsilon`): on a 100 000
|
|
203
|
+
person SIR epidemic the mean trajectory is within about 0.6% of the population
|
|
204
|
+
of the ODE solution at 0.03, and 0.2% at 0.01.
|
|
205
|
+
|
|
206
|
+
## Describe what is observed
|
|
207
|
+
|
|
208
|
+
Surveillance rarely sees compartments directly. It sees new cases per reporting
|
|
209
|
+
period, and only some of them. An `observe` statement defines such a quantity:
|
|
210
|
+
|
|
211
|
+
```
|
|
212
|
+
parameter rho = 0.5 prior uniform(0.05, 1) [1] -- fraction of infections reported
|
|
213
|
+
|
|
214
|
+
observe cases = rho * incidence(S -> I)
|
|
215
|
+
observe prevalence = I / N
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`incidence(S -> I)` is the number of people who moved from `S` to `I` since the
|
|
219
|
+
previous output time, so with `--points` set for weekly output it is a weekly
|
|
220
|
+
count. It is zero at the first output time. `incidence(-> S)` counts arrivals and
|
|
221
|
+
`incidence(I ->)` departures. When several flows share the same endpoints, they
|
|
222
|
+
are counted together.
|
|
223
|
+
|
|
224
|
+
Observables are written after the compartments in the output of `epidsl run`,
|
|
225
|
+
are summarised by `--runs`, and can be used as columns of the data given to
|
|
226
|
+
`epidsl calibrate`. In a composed model, each model's observables are kept: a
|
|
227
|
+
compartment name stands for its total over the other models, and an incidence
|
|
228
|
+
counts every transition in which that model makes the move.
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
uv run epidsl calibrate examples/sir_reporting.epidsl --data examples/sir_weekly_cases.csv --seed 1
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
parameter,mean,q0.025,q0.5,q0.975
|
|
236
|
+
beta,0.3038061462673391,0.252614404758703,0.3029811560539657,0.3620092080755828
|
|
237
|
+
rho,0.37209780074709964,0.16092360120134233,0.35308363011578686,0.6462532658218411
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The data are synthetic weekly counts produced with `beta = 0.3` and `rho = 0.4`.
|
|
241
|
+
The reporting fraction is less sharply determined than the transmission rate;
|
|
242
|
+
more `--populations` narrow both intervals.
|
|
243
|
+
|
|
244
|
+
An observable may declare a **noise distribution** with a tilde:
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
observe cases = incidence(S -> I) ~ poisson()
|
|
248
|
+
observe prevalence = I ~ negbinomial(5.0)
|
|
249
|
+
observe signal = rho * I ~ normal(10.0)
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
`poisson()` suits integer case counts; `negbinomial(phi)` suits overdispersed
|
|
253
|
+
counts (larger phi → less overdispersion); `normal(sd)` suits continuous
|
|
254
|
+
measurements. When calibrating, EpiDSL replaces the RMSE by the negative
|
|
255
|
+
log-likelihood of the declared distribution, which gives sharper posteriors for
|
|
256
|
+
count data. The stochastic backends (Gillespie, tau-leap) draw from the noise
|
|
257
|
+
distribution at each output time; the ODE backend always returns the
|
|
258
|
+
deterministic mean. See `examples/sir_noise.epidsl`.
|
|
259
|
+
|
|
260
|
+
## Calibrate parameters from data
|
|
261
|
+
|
|
262
|
+
Calibration estimates the parameters you are unsure of from observed counts. Give
|
|
263
|
+
each such parameter a prior, the range of values you consider plausible:
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
parameter beta = 0.3 prior uniform(0.05, 1) [1/day]
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Put the observations in a CSV file whose first column is `t` and whose other
|
|
270
|
+
columns are named after compartments or observables. Any subset will do:
|
|
271
|
+
|
|
272
|
+
```
|
|
273
|
+
t,I
|
|
274
|
+
0,10
|
|
275
|
+
10,69
|
|
276
|
+
20,200
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Then run:
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
uv run epidsl calibrate examples/sir.epidsl --data examples/sir_observed.csv --seed 1
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
The output has one row per parameter, with its estimated mean and the 2.5%, 50%
|
|
286
|
+
and 97.5% quantiles of its plausible values given the data:
|
|
287
|
+
|
|
288
|
+
```
|
|
289
|
+
parameter,mean,q0.025,q0.5,q0.975
|
|
290
|
+
beta,0.2866752974896084,0.264269375017657,0.28701743058810203,0.31155539756701467
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
The example data are synthetic: the model was run with `beta = 0.3` and noise was
|
|
294
|
+
added, so the estimate can be compared with the value that produced them.
|
|
295
|
+
|
|
296
|
+
A summary line on standard error reports the number of simulations, the final
|
|
297
|
+
tolerance and the effective sample size. `--out` writes the full weighted sample.
|
|
298
|
+
|
|
299
|
+
| Prior | Meaning |
|
|
300
|
+
|-------|---------|
|
|
301
|
+
| `uniform(a, b)` | Any value between `a` and `b`, equally likely. |
|
|
302
|
+
| `loguniform(a, b)` | Between `a` and `b`, with each order of magnitude equally likely. Both must be positive. |
|
|
303
|
+
| `normal(m, s)` | Centred on `m` with standard deviation `s`. |
|
|
304
|
+
|
|
305
|
+
The method is ABC-SMC (approximate Bayesian computation, sequential Monte Carlo;
|
|
306
|
+
Toni et al. 2009, with the adaptive kernel of Beaumont et al. 2009):
|
|
307
|
+
it repeatedly simulates the model with candidate values and keeps those whose
|
|
308
|
+
simulation is closest to the data, tightening the tolerance at each of
|
|
309
|
+
`--populations` rounds. It works with any `--method`. Each simulation starts at
|
|
310
|
+
time zero and reports exactly at the times in the data. The distance is the root
|
|
311
|
+
mean squared error, each series being divided by its largest observed value.
|
|
312
|
+
|
|
313
|
+
More populations or particles give a sharper estimate and take longer. A low
|
|
314
|
+
effective sample size relative to `--particles` means the estimate rests on few
|
|
315
|
+
particles: increase `--particles`.
|
|
316
|
+
|
|
317
|
+
### Use several processors
|
|
318
|
+
|
|
319
|
+
A calibration runs thousands of independent simulations, and an ensemble runs many.
|
|
320
|
+
`--workers` spreads them over that many processes, and `--workers 0` uses one per
|
|
321
|
+
processor:
|
|
322
|
+
|
|
323
|
+
```bash
|
|
324
|
+
uv run epidsl calibrate examples/sir_contact_matrix.epidsl --model ContactMatrix --data examples/contact_weekly_cases.csv --particles 300 --populations 12 --seed 1 --workers 0
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
That calibration takes 406 seconds on one processor and 81 seconds on eight — five
|
|
328
|
+
times faster, for the same answer. The number of workers changes how long a run
|
|
329
|
+
takes and nothing else: the seeds and the order of the work are fixed before any of
|
|
330
|
+
it is handed out, so a seeded run gives the same particles, the same tolerances and
|
|
331
|
+
the same count of simulations whatever `--workers` is set to.
|
|
332
|
+
|
|
333
|
+
Workers only pay off when there is enough work for them: starting them costs about
|
|
334
|
+
a second, since each loads NumPy and SciPy afresh.
|
|
335
|
+
|
|
336
|
+
## Compose models
|
|
337
|
+
|
|
338
|
+
A `compose` block builds the product of several models. Each model is read as an
|
|
339
|
+
automaton whose states are its compartments, in the manner of a stochastic automata
|
|
340
|
+
network; the result has one compartment per combination of states.
|
|
341
|
+
|
|
342
|
+
```
|
|
343
|
+
model Age {
|
|
344
|
+
compartment young = 300, old = 700
|
|
345
|
+
rate aging = 0.002 [1/day]
|
|
346
|
+
flow young -> old : aging * young
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
compose AgeSIR {
|
|
350
|
+
models: [SIR, Age]
|
|
351
|
+
}
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
`AgeSIR` has the compartments `S_young`, `S_old`, `I_young`, `I_old`, `R_young`
|
|
355
|
+
and `R_old`. Run it by name:
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
uv run epidsl run examples/sir_age.epidsl --model AgeSIR --t-end 160
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
The rules of composition:
|
|
362
|
+
|
|
363
|
+
- **Compartments** are named by joining the local names with `_`, in the order of
|
|
364
|
+
the `models` list. Initial values are the independent joint distribution: the
|
|
365
|
+
product of each model's initial values, divided by `N` for each extra model.
|
|
366
|
+
- **Flows** of each model are copied into every combination of the other models'
|
|
367
|
+
states.
|
|
368
|
+
- **Rates** keep their meaning. The name of a flow's source denotes the specific
|
|
369
|
+
source compartment (`S` becomes `S_young`); every other compartment name denotes
|
|
370
|
+
the total over the other models (`I` becomes `I_young + I_old`). Infection in
|
|
371
|
+
`AgeSIR` therefore mixes homogeneously across age groups.
|
|
372
|
+
- **Constants** of all models are merged. **Semantics** is the intersection.
|
|
373
|
+
|
|
374
|
+
A `sync` rule adds a transition that moves several models at once. Here a severe
|
|
375
|
+
infection changes a person's status and location in the same instant:
|
|
376
|
+
|
|
377
|
+
```
|
|
378
|
+
compose Hospital {
|
|
379
|
+
models: [Disease, Place]
|
|
380
|
+
sync S -> I, home -> hospital : severe * beta * S_home * I / N
|
|
381
|
+
}
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
In a `sync` rate, the source is named by joining the moves' sources (`S_home`).
|
|
385
|
+
With more than two models, a joined name that leaves some models out is a total
|
|
386
|
+
over them, and the rule is copied into each of their states.
|
|
387
|
+
|
|
388
|
+
### Make a rate depend on another model
|
|
389
|
+
|
|
390
|
+
Inside `compose`, `by` gives a constant of one model a value for each state of
|
|
391
|
+
another:
|
|
392
|
+
|
|
393
|
+
```
|
|
394
|
+
compose AgeStructured {
|
|
395
|
+
models: [Epidemic, Age]
|
|
396
|
+
parameter beta by Age = { young: 0.6, old: 0.3 }
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
`beta` is replaced by the constants `beta_young` and `beta_old`, and each
|
|
401
|
+
transition uses the one of the compartment it leaves: infection of `S_young` runs
|
|
402
|
+
at `beta_young * S_young * I / N`. Every state of the `by` model needs a value. The
|
|
403
|
+
unit is kept from the original constant unless a new one is given.
|
|
404
|
+
|
|
405
|
+
This expresses a rate that depends on the state of the individual who moves, such
|
|
406
|
+
as susceptibility by age.
|
|
407
|
+
|
|
408
|
+
### Say who meets whom
|
|
409
|
+
|
|
410
|
+
Naming the model twice gives one value per ordered pair of states — a contact
|
|
411
|
+
matrix. The row is the group being infected, the column the group it meets:
|
|
412
|
+
|
|
413
|
+
```
|
|
414
|
+
compose ContactMatrix {
|
|
415
|
+
models: [Epidemic, Age]
|
|
416
|
+
|
|
417
|
+
parameter beta by Age, Age = {
|
|
418
|
+
young, young: 0.9,
|
|
419
|
+
young, old: 0.15,
|
|
420
|
+
old, young: 0.15,
|
|
421
|
+
old, old: 0.35
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
The flow is still written once, in the component model, and is still
|
|
427
|
+
`flow S -> I : beta * S * I / N`. A rate that uses a matrix becomes the sum over the
|
|
428
|
+
states of `Age` of that rate, with the matrix on the pair (the state the flow
|
|
429
|
+
leaves, the state it meets) and each group of compartments restricted to that
|
|
430
|
+
state. The infection of the young is therefore generated as:
|
|
431
|
+
|
|
432
|
+
```
|
|
433
|
+
beta_young_young * S_young * I_young / N + beta_young_old * S_young * I_old / N
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
`N`, time and ordinary constants are untouched. A rate that uses a matrix must name
|
|
437
|
+
a group of compartments for the sum to range over, and one rate may use matrices of
|
|
438
|
+
one model only. A matrix is indexed by one model twice (`by Age, Age`); two
|
|
439
|
+
different models are not supported.
|
|
440
|
+
|
|
441
|
+
```bash
|
|
442
|
+
uv run epidsl run examples/sir_contact_matrix.epidsl --model ContactMatrix --t-end 120
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
Estimating the entries of a matrix from case data is possible but often weakly
|
|
446
|
+
determined: on the example above, four entries estimated from two weekly case
|
|
447
|
+
series give wide intervals, because very different matrices fit the data almost
|
|
448
|
+
equally well. Contact matrices are usually measured, not inferred.
|
|
449
|
+
|
|
450
|
+
### Say where newcomers enter
|
|
451
|
+
|
|
452
|
+
A model with an inflow, such as births, can be composed once every other model
|
|
453
|
+
states which of its compartments newcomers enter:
|
|
454
|
+
|
|
455
|
+
```
|
|
456
|
+
compose AgeStructured {
|
|
457
|
+
models: [Epidemic, Age]
|
|
458
|
+
enter Age at young
|
|
459
|
+
}
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
The inflow `flow -> S : mu * N` of `Epidemic` becomes `flow -> S_young : mu * N`.
|
|
463
|
+
|
|
464
|
+
### Model migration between patches
|
|
465
|
+
|
|
466
|
+
A metapopulation model couples a disease model with a "patch" model whose
|
|
467
|
+
compartments name the locations (cities, regions, age groups…). Migration between
|
|
468
|
+
patches is declared with a `migrate` statement and a matrix constant:
|
|
469
|
+
|
|
470
|
+
```
|
|
471
|
+
model City { compartment Paris = 5000, Lyon = 3000, Marseille = 2000 }
|
|
472
|
+
|
|
473
|
+
compose MetaSIR {
|
|
474
|
+
models: [SIR, City]
|
|
475
|
+
|
|
476
|
+
rate travel by City, City = {
|
|
477
|
+
Paris, Paris: 0,
|
|
478
|
+
Paris, Lyon: 0.005,
|
|
479
|
+
Paris, Marseille: 0.002,
|
|
480
|
+
Lyon, Paris: 0.005,
|
|
481
|
+
Lyon, Lyon: 0,
|
|
482
|
+
Lyon, Marseille: 0.003,
|
|
483
|
+
Marseille, Paris: 0.002,
|
|
484
|
+
Marseille, Lyon: 0.003,
|
|
485
|
+
Marseille, Marseille: 0
|
|
486
|
+
} [1/day]
|
|
487
|
+
|
|
488
|
+
migrate S, I, R : travel
|
|
489
|
+
}
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
`migrate S, I, R : travel` generates a cross-patch flow for every listed
|
|
493
|
+
compartment and every ordered pair of distinct patches. The entry `Paris, Lyon:
|
|
494
|
+
0.005` creates the flow `S_Paris -> S_Lyon : travel_Paris_Lyon * S_Paris`
|
|
495
|
+
(and likewise for `I` and `R`). Migration conserves population.
|
|
496
|
+
|
|
497
|
+
The rate matrix is declared inline in the `compose` block; it does not need a
|
|
498
|
+
prior declaration in `SIR` or `City`. Initial populations must be equal across
|
|
499
|
+
all composed models. The full example is in
|
|
500
|
+
[examples/metapop_sir.epidsl](examples/metapop_sir.epidsl).
|
|
501
|
+
|
|
502
|
+
### Observe and calibrate by stratum
|
|
503
|
+
|
|
504
|
+
A `compose` block can declare its own constants and observables. They are written
|
|
505
|
+
with the names of the composed model: a compartment such as `S_young`, a generated
|
|
506
|
+
constant such as `beta_young`, or a group name such as `I` or `young`, which stands
|
|
507
|
+
for a total.
|
|
508
|
+
|
|
509
|
+
```
|
|
510
|
+
compose AgeStructured {
|
|
511
|
+
models: [Epidemic, Age]
|
|
512
|
+
|
|
513
|
+
parameter beta by Age = { young: 0.6, old: 0.3 }
|
|
514
|
+
rate rho_young = 0.8 [1]
|
|
515
|
+
rate rho_old = 0.4 [1]
|
|
516
|
+
|
|
517
|
+
observe cases_young = rho_young * incidence(S_young -> I_young)
|
|
518
|
+
observe cases_old = rho_old * incidence(S_old -> I_old)
|
|
519
|
+
}
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
In `incidence`, a group name counts every transition between the two groups:
|
|
523
|
+
`incidence(S -> I)` is all new infections and `incidence(young -> old)` all ageing.
|
|
524
|
+
|
|
525
|
+
A parameter stratified with `by` keeps the prior of the original, or takes the one
|
|
526
|
+
written after its values (`... } prior uniform(0.1, 1)`). Each generated parameter
|
|
527
|
+
is then estimated separately:
|
|
528
|
+
|
|
529
|
+
```bash
|
|
530
|
+
uv run epidsl calibrate examples/sir_age_structured.epidsl --model AgeStructured --data examples/age_weekly_cases.csv --seed 1
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
```
|
|
534
|
+
parameter,mean,q0.025,q0.5,q0.975
|
|
535
|
+
beta_young,0.5977532401017741,0.32833100358229744,0.6015675486652726,0.8736703893495928
|
|
536
|
+
beta_old,0.3064468147009518,0.19243156341367465,0.2976122185897274,0.43279312186920177
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
The data are synthetic weekly cases by age group, produced with `beta_young = 0.6`
|
|
540
|
+
and `beta_old = 0.3`. With the default five populations the intervals are wide.
|
|
541
|
+
|
|
542
|
+
The full model is in
|
|
543
|
+
[examples/sir_age_structured.epidsl](examples/sir_age_structured.epidsl).
|
|
544
|
+
|
|
545
|
+
A composition is rejected when: a model is unknown or has errors; two models share
|
|
546
|
+
a compartment or constant name; the models' total populations differ or are zero;
|
|
547
|
+
they have no semantics in common; a joined or generated name is ambiguous or
|
|
548
|
+
already used; or a
|
|
549
|
+
model has an inflow (`flow -> A`) and another model has no `enter` statement.
|
|
550
|
+
Fewer than two models, and a malformed `sync`, `by` or `enter` statement, are
|
|
551
|
+
rejected too.
|
|
552
|
+
|
|
553
|
+
A composed model is an ordinary model: it can be listed in another `compose`
|
|
554
|
+
block, and `models: [A, B, C]` gives the same model as composing `A` and `B`
|
|
555
|
+
first.
|
|
556
|
+
|
|
557
|
+
## Language reference
|
|
558
|
+
|
|
559
|
+
| Statement | Meaning |
|
|
560
|
+
|-----------|---------|
|
|
561
|
+
| `model Name { ... }` | Declares a model. A file may hold several. |
|
|
562
|
+
| `compartment A = 10, B` | Declares compartments with initial values (default 0). |
|
|
563
|
+
| `parameter p = 0.3 [1/day]` | A named constant intended for calibration. The unit is optional. |
|
|
564
|
+
| `parameter p = 0.3 prior uniform(0.1, 1) [1/day]` | The same, with the prior that `epidsl calibrate` uses. |
|
|
565
|
+
| `rate g = 0.1 [1/day]` | A fixed named constant. The unit is optional. |
|
|
566
|
+
| `flow A -> B : expr` | Moves population from `A` to `B` at rate `expr`. |
|
|
567
|
+
| `flow -> A : expr` | Inflow (for example births). |
|
|
568
|
+
| `flow A -> : expr` | Outflow (for example deaths). |
|
|
569
|
+
| `observe x = expr` | A quantity derived from the state, written with the output. May use `incidence(A -> B)`. |
|
|
570
|
+
| `compose Name { ... }` | Declares the product of several models. |
|
|
571
|
+
| `models: [A, B]` | Inside `compose`: the models to compose, two or more. |
|
|
572
|
+
| `sync a -> b, c -> d : expr` | Inside `compose`: a transition that moves two or more models at once, one move per model. |
|
|
573
|
+
| `rate c by B = { x: 1, y: 2 }` | Inside `compose`: gives constant `c` one value per compartment of model `B`. Also with `parameter`. |
|
|
574
|
+
| `rate c by B, B = { x, x: 1, x, y: 2, ... }` | The same with one value per ordered pair: a contact matrix. |
|
|
575
|
+
| `enter B at x` | Inside `compose`: newcomers from another model's inflow enter `B` in compartment `x`. |
|
|
576
|
+
| `rate`, `parameter`, `observe` | Inside `compose`: extra constants and observables of the composed model. |
|
|
577
|
+
| `semantics: [ODE]` | Backends the model is valid for: `ODE`, `Gillespie`, `TauLeap`, `ABM`. Default `[ODE]`. |
|
|
578
|
+
|
|
579
|
+
Expressions support `+ - * / ^`, parentheses, the built-in symbols `N` (total
|
|
580
|
+
population) and `t` (time), and the functions `exp`, `log`, `sqrt`, `sin`, `cos`,
|
|
581
|
+
`abs`, `min`, `max`. Comments are `-- to end of line` and `/* block */`. A
|
|
582
|
+
trailing `;` after a statement is optional. The keywords (`model`, `compose`,
|
|
583
|
+
`compartment`, `parameter`, `rate`, `flow`, `semantics`, `models`, `sync`, `enter`,
|
|
584
|
+
`by`, `at`, `prior`, `observe`, `incidence`) cannot be used as names.
|
|
585
|
+
|
|
586
|
+
### Static checks
|
|
587
|
+
|
|
588
|
+
| Code | Severity | Condition |
|
|
589
|
+
|------|----------|-----------|
|
|
590
|
+
| C1 | error | A name is declared more than once. |
|
|
591
|
+
| C2 | error | A flow endpoint is not a compartment. |
|
|
592
|
+
| C3 | error | An expression uses an undefined symbol, an unknown function, or the wrong number of arguments. |
|
|
593
|
+
| C4 | error | A flow has the same compartment at both ends, or no endpoint at all. |
|
|
594
|
+
| C5 | warning | A `rate` or `parameter` has no unit. |
|
|
595
|
+
| C6 | error | An initial value is negative, or a declared value is not finite. |
|
|
596
|
+
| C7 | warning | A compartment, rate or parameter is never used. |
|
|
597
|
+
| C8 | error | A declaration reuses a reserved name (`N`, `t`, or a function name). |
|
|
598
|
+
| C9 | warning | A model has inflows but no outflows, or outflows but no inflows (unbounded population growth or decay). Demographic models with both are not warned. |
|
|
599
|
+
| C10 | error | The backend requested on the CLI (`--method`) is not listed in the model's `semantics`. |
|
|
600
|
+
| C11 | error | A prior is ill-defined (bounds in the wrong order, non-positive `loguniform` bound or standard deviation), or the parameter's value lies outside it. |
|
|
601
|
+
| C12 | error | `incidence` is used in a flow rate, or no flow has the endpoints it names. |
|
|
602
|
+
|
|
603
|
+
`--strict` turns warnings into errors.
|
|
604
|
+
|
|
605
|
+
### Command reference
|
|
606
|
+
|
|
607
|
+
| Command | Options |
|
|
608
|
+
|---------|---------|
|
|
609
|
+
| `epidsl check FILE` | `--strict` |
|
|
610
|
+
| `epidsl studio [FILE]` | `--port N` (default 8642, or a free port), `--no-browser` |
|
|
611
|
+
| `epidsl calibrate FILE` | `--data CSV` (required), `--method ode\|gillespie\|tau-leap` (default `ode`), `--particles N` (default 200), `--populations N` (default 5), `--seed N`, `--workers N`, `--model NAME`, `--out PATH`, `--strict` |
|
|
612
|
+
| `epidsl server` | (none) — start the LSP language server over stdio |
|
|
613
|
+
| `epidsl run FILE` | `--t-end T` (required), `--points N` (default 201), `--method ode\|gillespie\|tau-leap` (default `ode`), `--seed N`, `--runs K`, `--workers N`, `--quantiles Q1,Q2,...` (default `0.025,0.975`), `--epsilon E` (tau-leap only, default 0.03), `--model NAME`, `--out PATH`, `--strict` |
|
|
614
|
+
|
|
615
|
+
All commands exit with status 0 on success and 1 on any error.
|
|
616
|
+
|
|
617
|
+
## Develop
|
|
618
|
+
|
|
619
|
+
```bash
|
|
620
|
+
uv run pytest
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
```bash
|
|
624
|
+
uv run ruff check . && uv run ruff format --check . && uv run mypy
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
To run the tests against the oldest dependencies that `pyproject.toml` allows:
|
|
628
|
+
|
|
629
|
+
```bash
|
|
630
|
+
uv run --isolated --resolution lowest-direct pytest
|
|
631
|
+
```
|
|
632
|
+
|
|
633
|
+
To build the package and try it in a clean environment:
|
|
634
|
+
|
|
635
|
+
```bash
|
|
636
|
+
uv build
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
```bash
|
|
640
|
+
uv run --isolated --no-project --with dist/*.whl epidsl check examples/sir.epidsl
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
|
|
644
|
+
|
|
645
|
+
## Roadmap
|
|
646
|
+
|
|
647
|
+
1. **Done:** grammar, typed IR, checks C1–C8, ODE backend, CLI.
|
|
648
|
+
2. **Done:** `compose` blocks with `sync` rules, rates that depend on another model
|
|
649
|
+
(`by`) and entry states for inflows (`enter`).
|
|
650
|
+
3. **Done:** Gillespie and tau-leap stochastic backends, ensembles of runs.
|
|
651
|
+
4. **Done:** calibration by ABC-SMC, observables and incidence.
|
|
652
|
+
5. **Done:** release preparation (package builds and installs cleanly; not published).
|
|
653
|
+
6. **Done:** the studio, a visual workbench in the browser.
|
|
654
|
+
7. **Done:** contact matrices.
|
|
655
|
+
8. **Done:** running simulations over several processors; rates that depend on time
|
|
656
|
+
in the stochastic methods.
|
|
657
|
+
9. Network-based agent backend, language server, first PyPI release.
|
|
658
|
+
|
|
659
|
+
Design rationale, and how each method differs from the paper it follows, are
|
|
660
|
+
recorded in [docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md). References are in
|
|
661
|
+
[docs/references.bib](docs/references.bib).
|
|
662
|
+
|
|
663
|
+
## License
|
|
664
|
+
|
|
665
|
+
MIT
|