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
193           model with age groups`
195 - Another way to produce new individuals is using an action: ``clone``
196   (aka ``produce_offspring``) associated with a transition or
197   with a state (see :ref:`Set states attributes` and :ref:`Built-in
198   actions`).
200   .. seealso::
202      :ref:`SIR model with explicit gestation`
204 Remove transitions
205 ==================
207 State machines can also be used only for states, e.g. to differentiate
208 male/female individuals. In that case, the state machine does not
209 require any transition at all.
211 .. seealso::
213    :ref:`SIR model with explicit gestation`
215 Regulate time
216 *************
218 - The simulation time step can be changed either in the model file
219   (section ``time_info``), or at runtime with option ``-p
220   delta_t=value``
222 - Section ``time_info`` allows the definition of calendars with
223   events, for instance a pasture period:
225   .. admonition:: Example
227     .. code-block:: yaml
229        calendars:
230          pasture:
231            period: {days: 365}
232          events:
233            pasture_period: {begin: 'April 1', end: 'October 1'}
234            open_days: {date: 'May 1'}
236    A calendar can be periodic or not, and define events that span from
237    a ``begin`` date to and ``end`` date, or that take place at a
238    specific ``date``. Each event (here ``pasture_period`` and
239    ``open_days``) can be used in conditions, especially in the
240    ``when`` clause of transition or productions. A transition with
241    e.g. ``Not(pasture_period)`` will not be considered at all when the
242    condition is not fulfilled.
244    Besides, events with a begin and an end date automatically generate
245    two other events, here for instance ``begin_pasture_period`` and
246    ``end_pasture_period``.
248    .. seealso::
250       model :ref:`Quickstart <Test your installation>` provided to test
251       EMULSION installation
253 Complexify grouping
254 *******************
256 Grouping can be based on several variables, especially when the
257 dynamics of one process is affected by another one. For instance, if
258 infection is driven by age groups, the grouping section should be
259 rewritten as follows:
261 .. admonition:: Example
263   .. code-block:: yaml
265      grouping:
266        herd:
267          infection:
268            state_machine: health_state
269            key_variables: [health_state, age_group]
270          age_group:
271            state_machine: age_group
272            key_variables: [age_group]
274 .. seealso::
276    :ref:`SIR model with structured population`
278 Grouping are especially useful in hybrid models, either to accelerate
279 simulation time, or to benefit from :ref:`automatic variables
280 <Automatic variables>`.
282 A grouping can also be designed just to have access to specific
283 subgroups in the population, and thus indicate no state machine, nor
284 rely on variables related to state machines.
286 .. warning::
288    In any case, the name of the grouping must appear in the list of
289    processes: otherwise the grouping is not updated at each time step
290    (individuals are not distributed in the proper groups).
292 Aggregate variables
293 *******************
295 When defining levels, variables that aggregate other variables from a
296 sublevel can be defined, for instance:
298 .. admonition:: Example
300   .. code-block:: yaml
302      levels:
303        herd:
304          ...
305          aggregate_vars:
306            - name: pop_affected_over_time
307              collect: nb_episodes
308              operator: 'sum'
309            - name: 'avg_inf_duration'
310              collect: duration_infected
311              operator: 'mean'
313 Aggregated variables (here, ``pop_affected_over_time`` and
314 ``avg_inf_duration``) defined by a level (here, ``herd``) consist in
315 collecting the values of other variables (``nb_episodes``,
316 ``duration_infected``) in the sublevels (``individuals``) and applying
317 an operator (``sum``, ``mean``) to compute the resulting value.
319 Operators can be any classical usual operation operating on lists:
320 sum, prod, min, max, mean, var, std, median, all, any. Shortcuts have
321 been defined so that e.g. ``percentile20`` computes the 20th
322 percentile.
324 .. seealso:: :ref:`SIR model with individual actions and variable aggregation`
326 Automatic variables
327 *******************
329 EMULSION automatically provides variables in relation to model
330 components.
332 - ``step`` represents the current time step, ``delta_t`` the duration
333   of one time step (in time units), and ``time`` the time elapsed
334   since the beginning of simulation (in time units)
335 - When defining a level, e.g. ``herd``: ``total_herd`` gives the total
336   population of this level.
337 - When defining a state machine, e.g. ``health_state``, and its
338   states, e.g. ``S``:
340   - ``is_S`` tests whether or not an individual is in state ``S``
341   - ``duration_in_health_state`` contains the duration elapsed since
342     the individual entered the current state of state machine
343     ``health_state``
344   - ``total_S`` is the number of individuals in state ``S``
346 - When defining complex groupings, e.g. ``[age_group, health_state]``:
348   - ``total_J_I`` is the number of individuals in age group ``J`` and
349     in health state ``I``
350   - if aggregated variables (e.g. ``mean_age``) were also defined,
351     their counterpart is automatically defined for the grouping
352     (e.g. ``mean_age_J_I`` etc.)
354 .. seealso::
356    :ref:`SIRS model with periodic external risk`,
357    :ref:`SIR model with structured population`
360 Built-in functions
361 ******************
363 Expressions used in EMULSION models can refer to classical Python
364 mathematical operators (``+``, ``-``, ``*``, ``/``, ``**`` for
365 exponentiation, etc. ) and functions (e.g. ``sqrt``, ``cos``, ``sin``,
366 ``exp``, ``log``, ``log10``, etc.).
368 The following functions are also available:
370 ``AND(cond1, cond2)``
371     Logical conjunction: return true (1) if ``cond1`` and ``cond2`` are
372     both true, false (0) otherwise
374 ``OR(cond1, cond2)``
375     Logical disjunction: return true (1) if ``cond1`` is true or
376     ``cond2`` is true, false (0) otherwise
378 ``Not(cond)``
379     Logical negation: return true (1) if ``cond1`` and ``cond2`` are
380     both true, false (0) otherwise
382 ``IfThenElse(condition, val_if_true, val_if_false)``
383     Ternary conditional function: return either ``val_if_true`` or
384     ``val_if_false`` depending on ``condition``.
386 ``random_bool(proba_success)``
387     Return a random boolean value (0 or 1) depending on
388     ``proba_success``
391 Shortcuts to distributions from package ``numpy.random`` are also
392 available::
394     random_uniform(a, b)
395     random_integers(a, b)
396     random_exponential(m)
397     random_poisson(m)
398     random_beta(a, b)
399     random_normal(m, sd)
400     random_gamma = np.random.gamma(a, b)
402 .. seealso::
404    :ref:`Custom state durations`,
405    :ref:`SIRS model with periodic external risk`
408 Built-in actions
409 ****************
411 ``{action: action_name, d_params: dict_of_parameters}``
412    The generic keyword to call an external actions, requires Python code.
414    - ``action_name`` has to be described (``desc: ...``) explicitly in
415      main section ``actions``
416    - ``action_name`` must be provided in a separate Python file, as a
417      *method* in a class associated with the level at which the action
418      will be performed. This method will look as (assuming that
419      ``d_params`` contains two keys, ``param1`` and ``param2``):
421      .. admonition:: Example
423         .. code-block:: python
425            def action_name(self, param1, param2):
426                """Do somethin with *param1* and *param2* as specified in
427                section ``actions``"""
428                # here the Python code for the action
430    Whenever possible, prefer other built-in actions described below.
432 ``{message: 'Some important information'}``
433     Print the specified character string on the standard output while
434     running the model, preceded by the time step and the identifier of
435     the individual.
437 ``{set_var: varname, value: expression}``
438     Change the value of ``varname`` according to what is calculated in
439     ``expression``.
441     .. seealso::
443        :ref:`SIR model with individual actions and variable aggregation`
445 .. _clone_action:
447 ``{clone: a_prototype_or_list, amount: value, proba: value_or_list}``
448     Clone the individual into new ones. The newly produced individuals
449     follow the specified prototypes, according the given amount and
450     probabilities.
452     - default amount is 1
453     - if no probabilities are given, prototypes are considered
454       equiprobable
455     - a single prototype can be given as a single value instead of a
456       list
457     - the list or probabilites must be of same size of prototypes
458       list, only the last value may be omitted to ensure that the sum
459       of probabilities is 1. When N prototypes are associated with N
460       probability values which sum to S < 1, then there is a
461       probability 1-S to produce no offspring. Once probabilies are
462       actualized, a multinomial sampling is performed to determine the
463       number of new individuals in each category
465     .. admonition:: Example
467        A model with explicit gestation states and possibly vertical disease
468        transmission:
470        .. code-block:: yaml
472           - from: G
473             to: NG
474             proba: 1
475             on_cross:
476               - clone: [infected, healthy]
477                 amount: 1
478                 proba: [proba_vertical_transmission]
479                 # prototype 'healthy' has proba: 1-proba_vertical_transmission
481     ..seealso::
483       :ref:`SIR model with explicit gestation`
485 ``{produce_offspring: a_prototype_or_list, amount: value, proba: value_or_list}``
486     Synonym of ``clone``.
488 ``{become: a_prototype}``
489     Force the individual to adopt the specified prototype. Useful to
490     couple states from distinct state machines.
493 Changing scale: metapopulations
494 *******************************
496 In EMULSION, ``metapopulation`` is an aggregation type which allows to
497 handle multiple populations without regard to how this population is
498 built (compartment-based/hybrid/IBM).
500 It consists in defining a new level and completing initial conditions
501 through new population prototypes.
503 It may be also necessary to transform within-population parameters
504 into variables to allow for heterogeneous populations.
506 .. seealso::
508    :ref:`SIR model with metapopulation`
510 Connecting to Python code add-ons
511 *********************************
513 EMULSION is aimed at providing *generic* features required for
514 designing epidemiological models. Thus, some very specific operations
515 are not available in the generic engine. In such cases, a small code
516 add-on is required to provide additional functionalities.
518 Code add-ons are mainly used for specific requirements regarding:
520 - variables which are complicated to change through expressions and
521   actions
522 - actions which are not realizable through built-in ones
523 - processes which are not realizable through state machines
524 - complex intial conditions
525 - data loading
527 To link a level with a code add-on, two elements are required:
529 - ``file:`` which specified the Python source code to use
530 - ``class_name: AClassName`` which defines the name of the Python
531   class associated with the level
533 EMULSION provides an (experimental) code generator (``emulsion
534 generate MODEL.yaml``) which builds a code skeletton for files and
535 classes mentioned in the level definition. All actions and variables
536 listed respectively in ``actions`` and ``statevars`` sections, as well
537 as processes not associated with state machines or groupings, are
538 assumed to be defined in the Python file. All you need then is to fill
539 the relevant methods with the corresponding code, or remove
540 unnecessary parts.
542 .. seealso::
544    :ref:`SIR model with metapopulation and data-driven movements`