The Higher Education and Research forge

Home My Page Projects Code Snippets Project Openings EMULSION public releases
Summary Activity Surveys SCM Listes Sympa

SCM Repository

1 *****************************
2 Modelling language (advanced)
3 *****************************
5 EMULSION modelling language allows model designers to specify complex
6 assumptions in a readable way, to foster interactions with other
7 scientists and facilitate model revision throughout the design process
8 without having to dive into the simulation code.
10 Most language features documented below are associated with example
11 files, located in the ``models/features`` directory.
13 Compartments, IBM or hybrid models?
14 ***********************************
16 EMULSION helps to transform compartment-based models into
17 invidual-based models (or vice-versa, assuming the individual-based
18 model can get rid of individual specificities). An intermediate
19 approach is the hybrid model, which preserves individual
20 characteristics but drives system evolution through compartment-like
21 groupings (see: :ref:`Individuals, populations, metapopulations`).
23 The table below summarises the main differences between each kind of
24 models, regarding the sections and keywords to modify in an EMULSION
25 model file.
27 .. include:: paradigms.rst
29 .. seealso::
31    Also, in ``model/features``, many examples are provided with the
32    three modelling paradigms when possible, especially the simplest
33    SIR model (``compart_SIR.yaml``, ``hybrid_SIR.yaml``,
34    ``IBM_SIR.yaml``) and the corresponding version with demographic
35    processes (``compart_SIR_demo.yaml``, ``hybrid_SIR_demo.yaml``,
36    ``IBM_SIR_demo.yaml``).
38    See :ref:`SIR model`, :ref:`SEIRS model`, :ref:`SIR model with
39    basic demography (births/deaths)` and many others in :ref:`Feature
40    examples`.
42 Master state machines
43 *********************
45 Set states attributes
46 =====================
48 States can be endowed with *attributes*. For instance, ``fillcolor``
49 defines the color of the boxes on state machine diagrams, which is the
50 same than the color of plots in outputs.
52 A state can define three main properties:
54 ``autoremove: yes``
55     Autoremove states are intended as "sink", so that all individuals
56     that reach such a state are removed from the system. This is a
57     very convenient way to represent deaths or outgoing commercial
58     movements.
60     .. seealso::
62        :ref:`SIR model with basic demography (births/deaths)`
64 ``default: yes``
65     A state can be labelled as "default state". Default state plays
66     the same role but the way to use them differs in compartment-based
67     models and in others:
69     - in compartment-based models, when no indication is provided in
70       initial conditions or production links regarding new
71       individuals, they will be put in the default state for each of
72       their state machines
73     - in IBM/hybrid models and metapopulations, ``default`` is a valid
74       value for prototypes definition. For instance, writing
75       ``health_state: default`` in a prototype will set the health
76       state to the default state of the ``health_state`` state machine
78       .. seealso::
80          :ref:`Default state`, :ref:`SIR model with age groups`
82 ``duration`` (valid for **IBM**/**hybrid** models)
83     This keyword allows to assign a specific duration to a
84     state. Durations can be constant values or arbitrary expressions,
85     including a random distribution. When an individual enters the
86     state, it receives a value calculated from this expression
87     (possibly involving a random sample) and cannot leave this state
88     until the duration is over (with the exception of :ref:`escape
89     conditions <escape_conditions>`).
91     .. seealso::
93        :ref:`Custom state durations`
95 ``on_enter``, ``on_stay``, ``on_exit`` (valid for **IBM**/**hybrid** models)
96     These keywords are used to specify lists of **actions** that
97     individuals have to perform when, respectively, entering, staying
98     in, or leaving the state.
100     Actions can be either built-in actions (listed :ref:`there
101     <Built-in actions>`) or the name of a function provided in a code
102     add-on (e.g. ``action: my_custom_function``).
104     .. seealso::
106        :ref:`SIR model with individual actions and variable aggregation`
108 Customize transitions
109 =====================
111 In state machines, transitions are composed of at least three items:
113 .. _quantifiers:
115 - ``from`` followed by the origin state
116 - ``to`` followed by the destination state
117 - a **quantifier** to indicate the flow from origin to destination
118   state, which can be:
120   - ``rate`` with a transition rate per individual i.e. a number per
121     time unit. In stochastic models , rates are automatically
122     converted into probabilities, assuming that durations in the
123     origin state follow an exponential distribution
124   - ``proba`` with the probabiliy that, during *one time unit*, an
125     individual moves from origin to destination state
126   - ``amount`` which indicates an absolute number of individuals,
127     (bounded by the number of individuals actually in origin state)
128   - ``amount-all-but`` which indicates an absolute number of
129     individuals which have to *stay* in origin state while the others
130     move to destination state. Hence, writing ``amount-all-but: 0``
131     means "all individuals in origin state"
133 .. warning::
135    In a state machine, all quantifiers may be used. However, from a
136    given origin state, all transitions that can be used simultaneously
137    must have the same quantifiers (i.e. only ``rate``, or only
138    ``proba``, or only ``amount``/``amount-all-but``).
140 Transitions can also incorporate additional elements:
142 .. _escape_conditions:
144 - ``cond`` followed with a expression (logical or numeric, non-zero
145   values being considered true) specifies which individuals are
146   allowed to cross the transition
148   .. seealso:
150      :ref:`SIR model with age groups and explicit age`, :ref:`SIR
151           model with explicit gestation`
153 - ``escape`` is a special condition for origin states endowed with a
154   specific duration, which allows individuals that fulfil the
155   expression to exit their state *before* the normal term. For
156   instance, a gestating state has a duration before which individuals should
157   not be able to leave the state, but if abortions are possible, the
158   corresponding condition can be used as escape condition to permit a
159   premature exit of gestation.
161   .. seealso:
163      :ref:`SIR model with explicit gestation`
165 - ``when`` is a special condition which refers to *events* from a
166   :ref:`calendar <Regulate time>` (useful to handle seasonality)
167 - ``on_cross`` is used to specify a list of actions that indivuals
168   moving from origin state to destination state through this
169   transition have to perform
171   .. seealso:
173      :ref:`SIR model with explicit gestation`
176 Produce new individuals
177 =======================
179 - Section ``productions`` in state machines allow to define how some
180   states can produce new individuals. Production links are very
181   similar to transitions in their syntax, except that:
183   - ``escape`` conditions and ``amount-all-but`` quantifier are not allowed
184   - in IBM/hybrid models, a ``prototype`` must be specified for the new
185     individuals
187   Besides, the computation of actual flows uses sampling in Poisson
188   distribution rather than binomial/multinomial sampling.
190   .. seealso::
192      :ref:`SIR model with basic demography (births/deaths)`, :ref:`SIR model with age groups`
194 - Another way to produce new individuals is using an action: ``clone``
195   (aka ``produce_offspring``) associated with a transition or
196   with a state (see :ref:`Set states attributes` and :ref:`Built-in
197   actions`).
199   .. seealso::
201      :ref:`SIR model with explicit gestation`
203 Remove transitions
204 ==================
206 State machines can also be used only for states, e.g. to differentiate
207 male/female individuals. In that case, the state machine does not
208 require any transition at all.
210 .. seealso::
212    :ref:`SIR model with explicit gestation`
214 Regulate time
215 *************
217 - The simulation time step can be changed either in the model file
218   (section ``time_info``), or at runtime with option ``-p
219   delta_t=value``
221 - Section ``time_info`` allows the definition of calendars with
222   events, for instance a pasture period:
224   .. admonition:: Example
226     .. code-block:: yaml
228        calendars:
229          pasture:
230            period: {days: 365}
231          events:
232            pasture_period: {begin: 'April 1', end: 'October 1'}
233            open_days: {date: 'May 1'}
235    A calendar can be periodic or not, and define events that span from
236    a ``begin`` date to and ``end`` date, or that take place at a
237    specific ``date``. Each event (here ``pasture_period`` and
238    ``open_days``) can be used in conditions, especially in the
239    ``when`` clause of transition or productions. A transition with
240    e.g. ``Not(pasture_period)`` will not be considered at all when the
241    condition is not fulfilled.
243    Besides, events with a begin and an end date automatically generate
244    two other events, here for instance ``begin_pasture_period`` and
245    ``end_pasture_period``.
247    .. seealso::
249       model :ref:`Quickstart <Test your installation>` provided to test
250       EMULSION installation
252 Complexify grouping
253 *******************
255 Grouping can be based on several variables, especially when the
256 dynamics of one process is affected by another one. For instance, if
257 infection is driven by age groups, the grouping section should be
258 rewritten as follows:
260 .. admonition:: Example
262   .. code-block:: yaml
264      grouping:
265        herd:
266          infection:
267            state_machine: health_state
268            key_variables: [health_state, age_group]
269          age_group:
270            state_machine: age_group
271            key_variables: [age_group]
273 .. seealso::
275    :ref:`SIR model with structured population`
277 Grouping are especially useful in hybrid models, either to accelerate
278 simulation time, or to benefit from :ref:`automatic variables
279 <Automatic variables>`.
281 A grouping can also be designed just to have access to specific
282 subgroups in the population, and thus indicate no state machine, nor
283 rely on variables related to state machines.
285 .. warning::
287    In any case, the name of the grouping must appear in the list of
288    processes: otherwise the grouping is not updated at each time step
289    (individuals are not distributed in the proper groups).
291 Aggregate variables
292 *******************
294 When defining levels, variables that aggregate other variables from a
295 sublevel can be defined, for instance:
297 .. admonition:: Example
299   .. code-block:: yaml
301      levels:
302        herd:
303          ...
304          aggregate_vars:
305            - name: pop_affected_over_time
306              collect: nb_episodes
307              operator: 'sum'
308            - name: 'avg_inf_duration'
309              collect: duration_infected
310              operator: 'mean'
312 Aggregated variables (here, ``pop_affected_over_time`` and
313 ``avg_inf_duration``) defined by a level (here, ``herd``) consist in
314 collecting the values of other variables (``nb_episodes``,
315 ``duration_infected``) in the sublevels (``individuals``) and applying
316 an operator (``sum``, ``mean``) to compute the resulting value.
318 Operators can be any classical usual operation operating on lists:
319 sum, prod, min, max, mean, var, std, median, all, any. Shortcuts have
320 been defined so that e.g. ``percentile20`` computes the 20th
321 percentile.
323 .. seealso:: :ref:`SIR model with individual actions and variable aggregation`
325 Automatic variables
326 *******************
328 EMULSION automatically provides variables in relation to model
329 components.
331 - ``step`` represents the current time step, ``delta_t`` the duration
332   of one time step (in time units), and ``time`` the time elapsed
333   since the beginning of simulation (in time units)
334 - When defining a level, e.g. ``herd``: ``total_herd`` gives the total
335   population of this level.
336 - When defining a state machine, e.g. ``health_state``, and its
337   states, e.g. ``S``:
339   - ``is_S`` tests whether or not an individual is in state ``S``
340   - ``duration_in_health_state`` contains the duration elapsed since
341     the individual entered the current state of state machine
342     ``health_state``
343   - ``total_S`` is the number of individuals in state ``S``
345 - When defining complex groupings, e.g. ``[age_group, health_state]``:
347   - ``total_J_I`` is the number of individuals in age group ``J`` and
348     in health state ``I``
349   - if aggregated variables (e.g. ``mean_age``) were also defined,
350     their counterpart is automatically defined for the grouping
351     (e.g. ``mean_age_J_I`` etc.)
353 .. seealso::
355    :ref:`SIRS model with periodic external risk`,
356    :ref:`SIR model with structured population`
359 Built-in functions
360 ******************
362 Expressions used in EMULSION models can refer to classical Python
363 mathematical operators (``+``, ``-``, ``*``, ``/``, ``**`` for
364 exponentiation, etc. ) and functions (e.g. ``sqrt``, ``cos``, ``sin``,
365 ``exp``, ``log``, ``log10``, etc.).
367 The following functions are also available:
369 ``AND(cond1, cond2)``
370     Logical conjunction: return true (1) if ``cond1`` and ``cond2`` are
371     both true, false (0) otherwise
373 ``OR(cond1, cond2)``
374     Logical disjunction: return true (1) if ``cond1`` is true or
375     ``cond2`` is true, false (0) otherwise
377 ``Not(cond)``
378     Logical negation: return true (1) if ``cond1`` and ``cond2`` are
379     both true, false (0) otherwise
381 ``IfThenElse(condition, val_if_true, val_if_false)``
382     Ternary conditional function: return either ``val_if_true`` or
383     ``val_if_false`` depending on ``condition``.
385 ``random_bool(proba_success)``
386     Return a random boolean value (0 or 1) depending on
387     ``proba_success``
390 Shortcuts to distributions from package ``numpy.random`` are also
391 available::
393     random_uniform(a, b)
394     random_integers(a, b)
395     random_exponential(m)
396     random_poisson(m)
397     random_beta(a, b)
398     random_normal(m, sd)
399     random_gamma = np.random.gamma(a, b)
401 .. seealso::
403    :ref:`Custom state durations`,
404    :ref:`SIRS model with periodic external risk`
407 Built-in actions
408 ****************
410 ``{action: action_name, d_params: dict_of_parameters}``
411    The generic keyword to call an external actions, requires Python code.
413    - ``action_name`` has to be described (``desc: ...``) explicitly in
414      main section ``actions``
415    - ``action_name`` must be provided in a separate Python file, as a
416      *method* in a class associated with the level at which the action
417      will be performed. This method will look as (assuming that
418      ``d_params`` contains two keys, ``param1`` and ``param2``):
420      .. admonition:: Example
422         .. code-block:: python
424            def action_name(self, param1, param2):
425                """Do somethin with *param1* and *param2* as specified in
426                section ``actions``"""
427                # here the Python code for the action
429    Whenever possible, prefer other built-in actions described below.
431 ``{message: 'Some important information'}``
432     Print the specified character string on the standard output while
433     running the model, preceded by the time step and the identifier of
434     the individual.
436 ``{set_var: varname, value: expression}``
437     Change the value of ``varname`` according to what is calculated in
438     ``expression``.
440     .. seealso::
442        :ref:`SIR model with individual actions and variable aggregation`
444 .. _clone_action:
446 ``{clone: a_prototype_or_list, amount: value, proba: value_or_list}``
447     Clone the individual into new ones. The newly produced individuals
448     follow the specified prototypes, according the given amount and
449     probabilities.
451     - default amount is 1
452     - if no probabilities are given, prototypes are considered
453       equiprobable
454     - a single prototype can be given as a single value instead of a
455       list
456     - the list or probabilites must be of same size of prototypes
457       list, only the last value may be omitted to ensure that the sum
458       of probabilities is 1. When N prototypes are associated with N
459       probability values which sum to S < 1, then there is a
460       probability 1-S to produce no offspring. Once probabilies are
461       actualized, a multinomial sampling is performed to determine the
462       number of new individuals in each category
464     .. admonition:: Example
466        A model with explicit gestation states and possibly vertical disease
467        transmission:
469        .. code-block:: yaml
471           - from: G
472             to: NG
473             proba: 1
474             on_cross:
475               - clone: [infected, healthy]
476                 amount: 1
477                 proba: [proba_vertical_transmission]
478                 # prototype 'healthy' has proba: 1-proba_vertical_transmission
480     .. seealso::
482       :ref:`SIR model with explicit gestation`
484 ``{produce_offspring: a_prototype_or_list, amount: value, proba: value_or_list}``
485     Synonym of ``clone``.
487 .. _become_action:
489 ``{become: a_prototype_or_list, proba: value_or_list}``
490     Force the individual to adopt the specified prototype(s), possibly
491     with probabilities (works like ``clone``). Useful to couple states
492     from distinct state machines.
495 Changing scale: metapopulations
496 *******************************
498 In EMULSION, ``metapopulation`` is an aggregation type which allows to
499 handle multiple populations without regard to how this population is
500 built (compartment-based/hybrid/IBM).
502 It consists in defining a new level and completing initial conditions
503 through new population prototypes.
505 It may be also necessary to transform within-population parameters
506 into variables to allow for heterogeneous populations.
508 .. seealso::
510    :ref:`SIR model with metapopulation`
512 Connecting to Python code add-ons
513 *********************************
515 EMULSION is aimed at providing *generic* features required for
516 designing epidemiological models. Thus, some very specific operations
517 are not available in the generic engine. In such cases, a small code
518 add-on is required to provide additional functionalities.
520 Code add-ons are mainly used for specific requirements regarding:
522 - variables which are complicated to change through expressions and
523   actions
524 - actions which are not realizable through built-in ones
525 - processes which are not realizable through state machines
526 - complex intial conditions
527 - data loading
529 To link a level with a code add-on, two elements are required:
531 - ``file:`` which specified the Python source code to use
532 - ``class_name: AClassName`` which defines the name of the Python
533   class associated with the level
535 EMULSION provides an (experimental) code generator (``emulsion
536 generate MODEL.yaml``) which builds a code skeletton for files and
537 classes mentioned in the level definition. All actions and variables
538 listed respectively in ``actions`` and ``statevars`` sections, as well
539 as processes not associated with state machines or groupings, are
540 assumed to be defined in the Python file. All you need then is to fill
541 the relevant methods with the corresponding code, or remove
542 unnecessary parts.
544 .. seealso::
546    :ref:`SIR model with metapopulation and data-driven movements`