emulsion.tools package¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Misc. tools
Submodules¶
emulsion.tools.calendar module¶
Classes and functions for the definition of Emulsion calendars.

class
emulsion.tools.calendar.
EventCalendar
(calendar_name, step_duration, origin, period=None, **initial_dates)[source]¶ Bases:
object
The EventCalendar class is intended to handle events and periods of time. Dates/times are given to the calendar in a humanreadable format, and converted to integers (simulation steps).

__init__
(calendar_name, step_duration, origin, period=None, **initial_dates)[source]¶ Initialize the calendar using the specified information.
Parameters:  calendar_name (string) – the name of the calendar
 step_duration (
datetime.timedelta
) – actual duration of one simulation step  origin (
datetime.datetime
) – date/time value of the beginning of the calendar  period (
datetime.timedelta
) – if the calendar is periodic, actual duration of the period, None otherwise  initial_dates (dict) – initial dictionary of events (event name as key, dict as value with either begin/end dates or one single date if punctual event)

add_event
(name, begin_end)[source]¶ Add the specified event to the calendar. An event is characterized by its name and a begin_end tuple indicating the begin and end dates.
Parameters:  name (str) – the name of the event
 begin_end (tuple) – a tuple composed of the begin date and the end date (possibly identical for handling punctual events)

date_to_step
(date)[source]¶ Return the step corresponding the specified date.
Parameters: date ( datetime.datetime
) – the date to convert into time stepsReturns: t (int) – the time step during which the specified date occurs (the date occurs between the returned time step t and time step t+1)

get_events
()[source]¶ Return the list of events contained in the current calendar.
Returns: l (list) – the list of all event names


exception
emulsion.tools.calendar.
InvalidIntervalException
(begin, end)[source]¶ Bases:
Exception
Exception raised when trying to insert an inconsistent event in the calendar. An event is considered inconsistent if the begin date is posterior to the send date in a nonperiodic calendar.

emulsion.tools.calendar.
date_in
(begin, end, period=None)[source]¶ Build a function which tests if a date belongs to the specified interval (from begin to end). If a period is specified, the test relies upon the periodicity, otherwise dates are considered absolute.
Parameters:  begin (
datetime.datetime
) – the date when the interval begins  end (
datetime.datetime
) – the date when the interval ends  period (
datetime.timedelta
) – the duration of the period after which the calendar cycles
Returns: lambda – a function which maps a date (
datetime.datetime
) to abool
to indicate whether or not the date belongs to the beginend interval.Raises: InvalidIntervalexception
– if begin is posterior to end in a nonperiodic calendar begin (
emulsion.tools.functions module¶
Additional functions for symbolic computing in YAML model definition files.
All functions in this module can be used in EMULSION models.

emulsion.tools.functions.
AND
(*values)[source]¶ Return a logical AND (conjunction) between all the values.
Example
To define symptomatic individuals as infected for at least 5 days:
is_symptomatic: desc: 'test if individuals has symptoms' value: 'AND(is_I, duration_in_health_state >= 5)'
Parameters: *values (list) – boolean values separated by commas Returns: bool – True if all values are True, False otherwise.

emulsion.tools.functions.
IfThenElse
(condition, val_if_true, val_if_false)[source]¶ Ternary conditional function: return either val_if_true or val_if_false depending on condition.
Example
Here in a parameter definition (assuming that
summer_period
is defined e.g. in the calendars section of the model):average_temperature: desc: 'average temperature for the season' value: 'IfThenElse(summer_period, 25, 8)'
Parameters:  condition (bool) – a boolean expression
 val_if_true (number) – value to return if the expression is True
 val_if_false (number) – value to return if the expression is False
Returns: number – One of the two values, depending on condition.

emulsion.tools.functions.
MAX
(*values)[source]¶ Return a the maximum of all values.
Parameters: *values (list) – boolean values separated by commas Returns: float – the highest value

emulsion.tools.functions.
MIN
(*values)[source]¶ Return a the minimum of all values.
Parameters: *values (list) – boolean values separated by commas Returns: float – the lowest value

emulsion.tools.functions.
OR
(*values)[source]¶ Return a logical OR (disjunction) between all the values.
Example
To sell animals depending on either their weight or their age:
transitions: ...  from: Fattening to: Sold proba: 1 cond: 'OR(weight >= weight_thr, age >= age_thr)'
Parameters: *values (list) – boolean values separated by commas Returns: bool – True if at least one of the values is True, False otherwise.

emulsion.tools.functions.
random_beta
(a: float, b: float) → float[source]¶ Return a random value drawn from a beta distribution of parameters a and b.
Example
In a prototype definition:
age: 'random_beta(2, 5) * age_max'
Parameters:  a (float, positive (>0)) – first shape parameter of the beta distribution
 b (float, positive (>0)) – second shape parameter of the beta distribution
Returns: float – a random value sampled according to a beta distribution of parameters a and b
See also
numpy.random.beta()

emulsion.tools.functions.
random_bool
(proba_success: float) → int[source]¶ Return a random boolean value (actually, 0 or 1) depending on proba_success.
Example
Set the value of a state variable
has_symptoms
when entering in the infectious state:states: ...  I: ... on_enter:  set_var: has_symptoms value: 'random_bool(proba_symptomatic)'
Parameters: proba_success (float in [0,1]) – probability of returning 1 (True) Returns: int – either 1 with probability proba_success, or 0 with probability 1proba_success

emulsion.tools.functions.
random_choice
(*values)[source]¶ Return a value chosen randomly among those provided (equiprobable sampling).
Example
To init
age
among three typical values:prototypes: individuals: init_individual: age: 'random_choice(10, 50, 200)'
Parameters: *values (list) – the possible values, separated by commas Returns: val – one of the values (equiprobable choice)

emulsion.tools.functions.
random_choice_weighted
(*values)[source]¶ Return a value chosen randomly among those provided (but not equiprobably).
Example
To init
age
among three typical values which respectively represent 10%, 20% and 70% of the population:prototypes: individuals: init_individual: age: 'random_choice_weighted(10, 0.1, 50, 0.2, 200, 0.7)'
Parameters: values (list) – possibles choices and their weight, alternatively, separated by commas. Weights are normalized to be used as probabilities. Returns: One of the choices

emulsion.tools.functions.
random_exponential
(scale: float) → float[source]¶ Return a random value drawn from an exponential distribution of rate 1/scale (thus of mean scale).
Example
In a prototype definition:
time_to_live: random_exponential(mean_duration)
Parameters: scale (float) – the scale parameter of the distribution, i.e. the inverse of the rate Returns: float – a random value sampled according to an exponential distribution of rate 1/scale See also
numpy.random.exponential()

emulsion.tools.functions.
random_gamma
(shape: float, scale: float) → float[source]¶ Return a random value drawn from a gamma distribution of parameters shape and scale.
Example
In a prototype definition:
age: 'random_gamma(3, 2)'
Parameters:  shape (float, positive (>0)) – the shape of the gamma distribution
 scale (float, positive (>0)) – the scale of the gamma distribution
Returns: float – a random value sampled according to a gamma distribution of parameters shape and scale
See also
numpy.random.gamma()

emulsion.tools.functions.
random_integers
(low: int, high: int) → int[source]¶ Return a random integer value drawn from a discrete uniform distribution between low and high (both inclusive).
Example
In a prototype definition:
age: random_integers(min_age, max_age)
Parameters:  low (int) – lower boundary of the sample interval (inclusive)
 high (int) – upper boundary of the sample interval (inclusive)
Returns: int – a random integer value sampled according to a discrete uniform distribution between low and high
See also
numpy.random.random_integers()

emulsion.tools.functions.
random_multinomial
(number_of_samples, *probas)[source]¶ Return a multinomial sample based on the specified probabilities.
Parameters:  number_of_samples (int) – number of experiments
 probas (list) – list of probabilities
Returns: list – the drawn samples

emulsion.tools.functions.
random_normal
(mn: float, sd: float) → float[source]¶ Return a random value drawn from a normal distribution of mean mn and standard deviation sd.
Example
In a prototype definition:
age: 'random_normal(100, 5)'
Parameters:  mn (float) – the mean of the normal distribution
 sd (float, positive (>=0)) – the standard deviation of the normal distribution
Returns: float – a random value sampled according to a normal distribution of mean mn and standard deviation sd
See also
numpy.random.normal()

emulsion.tools.functions.
random_poisson
(lam: float) → int[source]¶ Return an integer random value drawn from a Poisson distribution of mean lam.
Example
In an action, e.g. here when computing how many newborn individuals will be produced:
 from: Gestating to: NonGestating on_cross:  produce_offspring: newborn amount: 'random_poisson(1.05)'
Parameters: lam (float) – the mean of the Poisson distribution Returns: int – a random integer value sampled according to a Poisson distribution of mean lam See also
numpy.random.poisson()

emulsion.tools.functions.
random_uniform
(low: float, high: float) → float[source]¶ Return a random value drawn from a uniform distribution between low (inclusive) and high (exclusive).
Example
In a prototype definition:
age: random_uniform(min_age, max_age)
Parameters:  low (float) – lower boundary of the sample interval (inclusive)
 high (float) – upper boundary of the sample interval (exclusive)
Returns: float – a random value sampled according to a uniform distribution between low and high
See also
numpy.random.uniform()
emulsion.tools.graph module¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Tools aimed at handling graphs for the state machines

class
emulsion.tools.graph.
EdgeTypes
¶ Bases:
emulsion.tools.state.EmulsionEnum
An enumeration.

PRODUCTION
= 2¶

TRANSITION
= 1¶

linestyle
= 'solid'¶


class
emulsion.tools.graph.
MultiDiGraph
(**attributes)[source]¶ Bases:
object
An oriented multigraph (two nodes can be linked by several edges). Replacement for MultiDiGraph in networkx with a reproducible order in accessing edges and nodes.

__init__
(**attributes)[source]¶ Create an instance of MultiDiGraph. If keywords arguments are specified, they are considered attributes of the whole graph.

add_edge
(from_id, to_id, type_id=<EdgeTypes.TRANSITION>, key=None, **attributes)[source]¶ Add the specified edge to the graph. If nodes are not already created, they are automatically added. Edge attributes can be specified. Since this graph allows multiple edges between pairs of nodes, two calls to this method lead to two distinct edges (even if the attributes are the same), unless a key is specified. The key is used to identify edges between a given pair of nodes. By default, keys are consecutive integers.

emulsion.tools.misc module¶
Collection of various useful functions used in EMULSION framework, especially regarding introspection.

emulsion.tools.misc.
AGENTS
= 1¶ Constant value for the index where list of agents are stored in ‘populations’ tuples.

emulsion.tools.misc.
POPULATION
= 1¶ Constant value for the index where population amounts are stored in ‘populations’ tuples.

emulsion.tools.misc.
add_new_property
(agent, property_name, getter_function)[source]¶ Add a new property to an agent.
Actually, the property is added to the class of the agent, as Python properties are descriptors. Yet, the dynamic attribution of properties must me done through instances rather than classes, since agents must add the name of the property to their
_mbr_cache
attribute.Parameters:  agent (AbstractAgent) – the agent to which the property must be added
 property_name (str) – the name of the property
 getter_function (lambda) – the function upon which the property is built

emulsion.tools.misc.
aggregate_probabilities
(probability_values: Iterable[float], delta_t: float) → Iterable[float][source]¶ From the specified probability_values, intended to represent probabilities of events duting one time unit, compute the probabilities for the specified time step (delta_t).
Parameters:  probability_values (list) – a list of probability values for several events (during 1 time unit)
 delta_t (float) – the value of the time step (expressed in time units)
Returns: list – the probabilities of the same events during delta_t time units.

emulsion.tools.misc.
aggregate_probability
(probability: float, delta_t: float) → float[source]¶ Transform the specified probability value, intended to represent a probability for events tested each time unit, into the probability for the specified time step (delta_t).
Parameters:  probability (float) – the probability value of an event (during 1 time unit)
 delta_t (float) – the value of the time step (expressed in time units)
Returns: float – the probability of the event during delta_t time units.

emulsion.tools.misc.
count_population
()[source]¶ Return the amount of atoms represented in agents_or_pop.
Parameters: agents_or_pop (tuple) – either (‘population’, qty) or (‘agents’, list of agents) Returns: int or float – the amount corresponding to the population: generally, an int value, but deterministic models produce float values.

emulsion.tools.misc.
create_aggregator
(sourcevar: str, operator: str)[source]¶ Create an aggregator function to be used as property getter. This aggregator function has to collect all values of sourcevar for agents contained in a given host, and reduce them to one avalue using the specified operator.
Parameters:  sourcevar (str) – the name of the variable to collect in the sublevel
 operator (str) – the name of the operator to apply to the collected values
Returns: lambda – A function which can be applied to a MultiProcessManager agent (i.e. with explicit sublevel agents) which returns the aggregated values for the whole population.

emulsion.tools.misc.
create_atoms_aggregator
(sourcevar: str, operator: str, machine_name: str, state_name: str)[source]¶ Build a getter for property of the form
newvar_X
whereX
if the value of state_name (a state of state_machine),newvar
is an aggregate variable based on collecting all values of sourcevar for the specific group_name and aggregating the values using operator. This function is intended to work on IBMProcessManager agents, which do not benefit from groupings.Parameters:  sourcevar (str) – the name of the variable to collect in the sublevel
 operator (str) – the name of the operator to apply to the collected values
 machine_name (str) – the name of the state machine for which the getter is created
 state_name (str) – the state name
Returns: lambda – A function which can be applied to an IBMProcessManager agent (i.e. with explicit but ungrouped sublevel agents) which returns the aggregated value for the specified group.

emulsion.tools.misc.
create_group_aggregator
()[source]¶ Build a getter for property of the form
newvar_X_Y
whereX
andY
are states of two different states machines used in a grouping,newvar
is an aggregate variable based on collecting all values of sourcevar for the specific group_name and aggregating the values using operator. The functions can handle groupings with an arbitrary number of states.Parameters:  sourcevar (str) – the name of the variable to collect in the sublevel
 operator (str) – the name of the operator to apply to the collected values
 process_name (str) – the name of the process associated with the grouping for which the population getter is created
 group_name (str or tuple) – either a string representing the state name (if only one), or a tuple of several state names
Returns: lambda – A function which can be applied to an MultiProcessManager agent (i.e. with explicit sublevel agents) which returns the aggregated value for the specified group.

emulsion.tools.misc.
create_new_serial
(end=None, model=None)[source]¶ Create the serial number generator associated to the specified variable.

emulsion.tools.misc.
create_population_getter
()[source]¶ Build a getter for property of the form
total_X_Y
whereX
andY
are states of two different states machines used in a grouping.The functions can handle groupings with an arbitrary number of states.
Parameters:  process_name (str) – the name of the process associated with the grouping for which the population getter is created
 group_name (str or tuple) – either a string representing the state name (if only one), or a tuple of several state names
Returns: callable – A function which can be applied to an AbstractProcessManager agent which returns the population size for the specified group.

emulsion.tools.misc.
create_weighted_random
(machine_name, weights, model=None)[source]¶ Create a random choice function which returns a random state from the given state machine (among nonautoremove states), according to the weights. Weights are interpreted either directly as probabilities (if the number of weights is stricly one below the number of available states, the last state getting the complement to 1), or as true weights which are then normalized to be used as probabilities.
 machine_name: str
 the name of the state machine where the states must be chosen among the N nonautoremove states.
 weights: list
 a list of N or N1 model expressions assumed to produce positive numbers
 model: EmulsionModel
 the model where this function is defined
Returns: lambda (a function that returns a random state according to the) – values of the weights list, interpreted either as probabilities (if size N1) or as weights (if size N) which are then normalized to provide probabilities

emulsion.tools.misc.
find_operator
(operator: str)[source]¶ Return an aggregation function named operator.
Search starts with emulsion functions (module emulsion.tools.functions), which includes Python builtins, then in numpy.
A special shortcut is provided for percentiles:
percentileXX
is interpreted as the partial functionnumpy.percentile(q=int(XX))
.Parameters: operator (str) – the name of the aggregation operator Returns: lambda – a function that takes a list (or arraylike) as input and returns the application of the operator to the values.

emulsion.tools.misc.
load_class
(module=None, class_name: str = None, options: dict = {})[source]¶ Dynamically load the class with the specified class_name from the given module.
Parameters:  module – a Python module, where the class is expected to be located.
 class_name (str) – the name of the class to load
 options – some options
Returns: tuple – a tuple composed of the class (type) and the options.
Todo
 clarify the role of options

emulsion.tools.misc.
load_module
(module_name: str)[source]¶ Dynamically load the module with the specified module_name and return it.
Parameters: module_name (str) – the name of a valid Python module (accessible in the PYTHONPATH
environment variable).Returns: ref – A reference to the Python module.

emulsion.tools.misc.
moving_average
(values, window_size, mode='same')[source]¶ Compute a moving average of the specified values with respect to the window_size on which the average is calculated. The return moving average has the same size as the original values. To avoid boundary effects, use
mode='valid'
, which produce a result of sizelen(values)  window_size + 1
.Parameters:  values (arraylike) – contains the values for moving average computation
 window_size (int) – width of the moving average window
 mode (str) – a parameter for numpy.convolve
Returns: nd_array – a numpy
nd_array
containing the values of the moving average.

emulsion.tools.misc.
probabilities_to_rates
(probability_values: Iterable[float]) → List[float][source]¶ Transform a list of probabilities into a list of rates. The last value is expected to represent the probability of staying in the current state.
Parameters: probability_values (list) – a list of probabilities, the last one representing the probability to stay in the current state Returns: list – a list of rates corresponding to those probabilities.

emulsion.tools.misc.
rates_to_probabilities
(total_rate: float, rate_values: List[float], delta_t: float = 1) → List[float][source]¶ Transform the specified list of rate_values, interpreted as outgoing rates, into probabilities, according to the specified time step (delta_t) and normalized by total_rate.
For exit rates \(\rho_i\) (one of the rate_values), the probability to stay in current state is given by:
\[p_0 = e^{\delta t.\sum_i \rho_i}\]Thus, each rate \(\rho_i\) corresponds to a probability
\[p_i = \frac{\rho_i}{\sum_i \rho_i} (1  p_0)\]Parameters:  total_rate (float) – the total exit rate, used for normalization purposes. If rate_values represent all possible exit rates, total_rate is their sum.
 rate_values (list) – the list of rates to transform
 delta_t (float) – the value of the time step (expressed in time units)
Returns: list – the list of probabilities corresponding to the rate_values.

emulsion.tools.misc.
read_from_file
(filename: str)[source]¶ Read the specified YAML filename and return the corresponding Python document.
Parameters: filename (str) – the name of the YAML file to load Returns: object – a Python object built by parsing of the YAML file, i.e. either a dict, list, or even str/int/etc… (Most YAML document will produce dictionaries.)

emulsion.tools.misc.
retrieve_value
(value_or_function, agent)[source]¶ Return a value either directly given by parameter value_or_function if it is a true value, or computed from this parameter seen as a function, with the specified agent as argument.
Parameters:  value_or_function – either a callable (function that applies to an agent to retrieve an individual value), or the value itself
 agent – the agent to use as parameter of the callable if necessary
Returns: value – the expected value (agentbased or not).

emulsion.tools.misc.
select_random
(origin: Iterable, quantity: int, exclude: sortedcontainers.sortedset.SortedSet = SortedSet([], key=None, load=1000)) → List[source]¶ Return a random selection of quantity agents from the origin group, avoiding those explicitly in the exclude set. If the origin population proves too small, all available agents are taken, irrespective to the quantity.
Parameters:  origin (iterable) – the population where agents must be selected
 quantity (int) – the number of agents to select in the population
 exclude (set) – agents which are not available for the selection
Returns: list – a list of randomly selected agents according to the above constraints.
emulsion.tools.parallel module¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Tools for parallel computing.

emulsion.tools.parallel.
job
(target_simulation_class, proc, **others)[source]¶ Simple job for a simple processes

emulsion.tools.parallel.
job_dist
(total_task, workers)[source]¶ Return a distribution of each worker need to do.
emulsion.tools.plot module¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Plotting tools… to be improved!

emulsion.tools.plot.
build_machine_plot
(machine_name, model, params)[source]¶ Return a bokeh figure based on the representation of the state machine, with the associated colors.
Parameters: machine – the state machine to which the states are related Returns: A bokeh gridplot.

emulsion.tools.plot.
build_state_plot
(counts, cols, machine, model, y='quantity', group='state', ylab='Number of individuals')[source]¶ Return a bokeh figure based on the representation of the states in the counts dataframe, with the associated colors.
Parameters:  counts – a Pandas dataframe containing the values to plot
 cols (dict) – dictionary which maps state/variable names to colors
 machine – the state machine to which the states are related
 model – the Emulsion model related to this plot
 y (str) – the name of the field containing y values in the dataframe
 group (str) – either ‘state’ (default) or ‘variables’, name of the field containing each legend items.
Returns: A bokeh gridplot (reduced to one figure a the herd level, one figure per herd at metapopulation level).
emulsion.tools.simulation module¶
Tools for providing generic simulation classes.

class
emulsion.tools.simulation.
AbstractSimulation
(start_id: int = 0, model=None, model_path: str = '', stock_agent: bool = True, output_dir: str = 'outputs/', target_agent_class=None, save_results: bool = True, input_dir: str = None, load_from_file: str = None, save_to_file: str = None, **_)[source]¶ Bases:
object
Abstract class from which any simulation class inherits.

__init__
(start_id: int = 0, model=None, model_path: str = '', stock_agent: bool = True, output_dir: str = 'outputs/', target_agent_class=None, save_results: bool = True, input_dir: str = None, load_from_file: str = None, save_to_file: str = None, **_)[source]¶ Initialize the simulation.
Parameters:  start_id – ID of the (first) simulation
 model – instance of the model to run
 model_path – path to the filename holding the description of the model, used if model is None
 stock_agent – TODO
 output_dir – name of the directory for simulation outputs
 target_agent_class – agent class representing the top level in the simulation
 save_results – True if simulation outputs have to be saved, False otherwise. TODO: should be removed, and replaced by a set of OutputManagers dedicated to the specific expected outputs.
 load_from_file – a filename from which the initial state of the simulation (agents corresponding to levels with their state) is read (instead of running the initialize_level method)
 save_to_file – a filename in which the final state of the simulation (agents corresponding to levels with their state) is written (after running the finalize_level method)


class
emulsion.tools.simulation.
MultiSimulation
(multi_id: int = 0, nb_simu: int = 100, set_seed: bool = False, silent: bool = False, quiet: bool = False, dparams: dict = {}, **others)[source]¶ Bases:
emulsion.tools.simulation.AbstractSimulation
MultiSimulation can handle multiple repetitions of a given model. For sensibility study (same model with different values of variables), please check out SensitivitySimulation.

__init__
(multi_id: int = 0, nb_simu: int = 100, set_seed: bool = False, silent: bool = False, quiet: bool = False, dparams: dict = {}, **others)[source]¶ Initialize a simulation with multiple repetitions of the same model.

counts
¶


class
emulsion.tools.simulation.
OutputManager
(model=None, output_dir='', output_file='counts.csv', log_file='log.txt')[source]¶ Bases:
object
Manager to handle different outputs (csv, database,… etc)

class
emulsion.tools.simulation.
SensitivitySimulation
(scenario_path=None, df=None, nb_multi=None, **others)[source]¶ Bases:
emulsion.tools.simulation.AbstractSimulation
SensitivitySimulation can handle sensibility study with a given pandas DataFrame of parameters or a path linked with file which contains scenarios of parameters. Then it will be transformed to a dictionary of scenario in the
`d_scenario`
attribute. For instance, d_scenario could be the form (QFever model example) :
 {0: {‘m’: 0.7, ‘q’: 0.02 …},
 1: {‘m’: 0.5, ‘q’: 0.02 …}, 2: …, … }

__init__
(scenario_path=None, df=None, nb_multi=None, **others)[source]¶ Initialize the simulation.
Parameters:  start_id – ID of the (first) simulation
 model – instance of the model to run
 model_path – path to the filename holding the description of the model, used if model is None
 stock_agent – TODO
 output_dir – name of the directory for simulation outputs
 target_agent_class – agent class representing the top level in the simulation
 save_results – True if simulation outputs have to be saved, False otherwise. TODO: should be removed, and replaced by a set of OutputManagers dedicated to the specific expected outputs.
 load_from_file – a filename from which the initial state of the simulation (agents corresponding to levels with their state) is read (instead of running the initialize_level method)
 save_to_file – a filename in which the final state of the simulation (agents corresponding to levels with their state) is written (after running the finalize_level method)

counts
¶

class
emulsion.tools.simulation.
Simulation
(steps: int = 100, simu_id: int = 0, silent: bool = False, quiet: bool = False, **others)[source]¶ Bases:
emulsion.tools.simulation.AbstractSimulation
Simulation class is aimed at running one repetition of a given model (for several repetitions, use MultiSimulation).

__init__
(steps: int = 100, simu_id: int = 0, silent: bool = False, quiet: bool = False, **others)[source]¶ Create an instance of simulation.
Parameters:  steps – number of time steps to run
 simu_id – ID of the simulation
 silent – if False, show a progress bar during simulation execution
 quiet – if True, show no progressbar at all

counts
¶ Return a pandas DataFrame contains counts of each process if existing. TODO: column steps need to be with one of process and NO column steps for inter herd

emulsion.tools.state module¶
This module defines:
 a class
StateVarDict
which is a special autoreferential dictionary to handle state variables  a class
EmulsionEnum
which is a special kind of enumeration intended to handle states from state machines

class
emulsion.tools.state.
EmulsionEnum
[source]¶ Bases:
enum.Enum
This class represents enumerations for states of state machines in EMULSION. They are endowed with some special features:
 They provide total ordering between items (based on
__lt__
and__eq__
methods).  A comparison with
None
is provided (any state is always greater thanNone
).  Other features will be developed soon.
 They provide total ordering between items (based on

class
emulsion.tools.state.
StateVarDict
(*args, **kwargs)[source]¶ Bases:
dict
A special dictionary aimed at handling the state variables of agents in EMULSION models. In addition to the classical dict keybased access, it provides an attributelike access syntax.
This class is used in EMULSION to store agent properties. Such properties include those defined automatically and used by the EMULSION engine, such as the values of the states for each state machine, the current time step, or “hidden” values such as the time spent in the current state for each state machine. They are also used to include userdefined attributes (e.g. age, weight…).
When searching for a model
statevar
, the engine tries first to find a classical instance variable (which can be mimicked by a Python@property
decored function), then looks inside the agent’sstatevar
attribute; finally, the search continues in the agent’s host (if any).Example
s = StateVarDict(age=10, sick=True) s['age'] += 1 s.sick = False s.new_property = 'Wow !'
emulsion.tools.timing module¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Tools for performance assessment.
emulsion.tools.view module¶
A Python implementation of the EMuLSion framework (Epidemiologic MUltiLevel SImulatiONs).
Tools for data / map visualization.

emulsion.tools.view.
build_animation
(values, title, unit=None, filename=None, cmap='coolwarm', framerate=10, resolution=100, writer='imagemagick', **kwargs)[source]¶ Create an animation based on the
values
list, with the specified title. A special color map name can be specified, as well as the presence of a colorbar and additional keyword arguments passed toimshow
. If a specified unit is given, each frame is marked with its number and the corresponding unit. If a filename is provided in thesave
parameter, the animation is stored in that file.

emulsion.tools.view.
show_contour
(value, cmap='hot', save=None, colbar=False, **kwargs)[source]¶ Display the specified value as a contour map with values. A special color map name can be specified, as well as the presence of a colorbar and additional keyword arguments passed to
contourf
. If a filename is provided in thesave
parameter, the image is stored in that file.

emulsion.tools.view.
show_histo
(value, xlabel, facecol='green', save=None)[source]¶ Display the distribution of the specified
value
array usingxlabel
for the legend. A specific face color can be used. If a filename is provided in thesave
parameter, the image is stored in that file.

emulsion.tools.view.
show_img
(value, cmap='hot', save=None, colbar=True, **kwargs)[source]¶ Display the specified value as an image. A special color map name can be specified, as well as the presence of a colorbar and additional keyword arguments passed to
imshow
. If a filename is provided in thesave
parameter, the image is stored in that file.