Stochastic Models

Contains a general base class to define stochastic epidemiological models in populations of constant size.

class epipack.stochastic_epi_models.StochasticEpiModel(compartments, N, edge_weight_tuples=None, directed=False, well_mixed_mean_contact_number=1)[source]

Bases: object

A general class to define any compartmental epidemiological model that can be run in a well-mixed system or on a weighted, directed network. By default, the epidemiological process is considered to run in a well-mixed system.

Parameters

  • compartments (list of string) -- A list containing compartment strings.

  • N_nodes (int) -- The number of nodes in the system.

  • edge_weight_tuples (list of tuples of (int, int, float), default = None) --

    Choose this ption The links along which transmissions can take place.

    [ (source_id, target_id, weight), ... ]

  • directed (bool, default = False) -- If directed is False, each entry in the edge_weight_tuples is considered to equally point from target_id to source_id with weight weight.

  • well_mixed_mean_contact_number (int, default = 1) -- By default, the epidemiological process is considered to run in a well-mixed population where for each link-transmission event, a node is assumed to have contact to exactly one other node. Increase this contact number by adjusting this parameter.

compartments

A list containing strings or other hash-able types that describe each compartment, (e.g. "S", "I", etc.).

Type

list of string

N_comp

Number of compartments (including population number)

Type

int

node_status

Each entry gives the compartment that the corresponding node is part of.

Type

numpy.ndarray of int

Example

>>> epi = StochasticEpiModel(["S","I","R"],10)
>>> print(epi.compartments)
[ "S", "I", "R" ]
get_compartment(iC)[source]

Get the compartment, given an integer ID iC

get_compartment_changes()[source]

Let an event take place according to the new time and return the change in compartment counts.

get_compartment_id(C)[source]

Get the integer ID of a compartment C

get_reacting_node()[source]

Get a reacting node with probability proportional to its reaction rate.

get_time_leap()[source]

Sample a time leap from an exponential distribution according to the current total event rate

get_total_event_rate()[source]

Get the total event rate.

get_true_total_event_rate()[source]

Get the true total event rate.

make_node_event(reacting_node, event, neighbor=None)[source]

Let a specific node event happen

Parameters

  • reacting_node (int) -- the index of the node that reacts

  • event (tuple of int) -- three-entry long tuple that characterizes this event

  • neighbor (int, default = None) -- specify the neighbor to which this specific event happens

Returns

compartment_changes -- Each tuple contains the index of the compartment that loses a member on the first position and the index of the compartment that gains a member.

Return type

list of tuples of int

make_random_node_event(reacting_node)[source]

Let a random node event happen according to the event probabilities of this node's status.

Parameters

reacting_node (int) -- the index of the node that reacts

Returns

compartment_changes -- Each tuple contains the index of the compartment that loses a member on the first position and the index of the compartment that gains a member.

Return type

list of tuples of int

reactions_may_still_occur(state)[source]

Reactions can only take place if there's still nodes that can transmit AND nodes that can be infected or spontaneously change state.

Define link transmission processes between compartments.

Parameters

process_dict (list of tuple) --

A dictionary of tuples that contains conditional transmission events in the following format:

{
    ( "source_base", "->", "target_base" ): [
        ("target_base",
         "target_compartment_initial",
         probability
         "target_base",
         "target_compartment_final",
         ),
    ...
   ],
    ( "infecting", "source_base", "->", "infecting", "target_base" ): [
        ("target_base",
         "target_compartment_initial",
         "->"
         "target_base",
         "target_compartment_final",
         ),
    ...
   ]
}

Example

When an I-node recovers (to R), scan all of the newly-recovered node's neighbors. If the neighbor is an S, transition the neighbor to X. If the neighbor is an I, transition the neighbor to Q with probability \(p\) (implying that nothing happens to this neighbor with probability \(1-p\).

epi.set_conditional_link_transmission_processes({
    ( "I", "->", "R" ) : [
        ("R", "S", "->", "R", "X" ),
        ("R", "I", p, "R", "Q" ),
    ]
})

Define link transmission processes between compartments.

Parameters

process_list (list of tuple) --

A list of tuples that contains transitions rates in the following format:

[
    ("source_compartment",
     "target_compartment_initial",
     rate
     "source_compartment",
     "target_compartment_final",
     ),
    ...
]

Example

For an SEIR model.

epi.set_link_transmission_processes([
    ("I", "S", +1, "I", "E" ),
])
set_network(N_nodes, edge_weight_tuples, directed=False)[source]

Define the model to run on a network.

Parameters

  • N_nodes (int) -- Number of nodes in the system

  • edge_weight_tuples (list of tuple of (int, int, float)) --

    The links along which transmissions can take place.

    [ (source_id, target_id, weight), ... ]

  • directed (bool, default = False) -- If directed is False, each entry in the edge_weight_tuples is considered to equally point from target_id to source_id with weight weight.

set_node_status(node, status)[source]

Set the status of node node to status

Parameters

  • node (int) -- The index of the node

  • status (int) -- The index of the compartment that the node changes into.

set_node_statuses(node_status)[source]

Set all node statuses at once and evaluate events and rates accordingly. Can be used to set initial conditions.

Parameters

node_status (numpy.ndarray of int) -- For each node, this array contains the node's compartment index.

set_node_transition_processes(process_list)[source]

Define the linear node transition processes between compartments.

Parameters

process_list (list of tuple) --

A list of tuples that contains transitions rates in the following format:

[
    ("source_compartment", rate, "target_compartment" ),
    ...
]

Example

For an SEIR model.

epi.set_node_transition_processes([
    ("E", symptomatic_rate, "I" ),
    ("I", recovery_rate, "R" ),
])
set_random_initial_conditions(initial_conditions)[source]

Set random initial conditions for each compartment.

Parameters

initial_conditions (dict) -- A dictionary that maps a compartment to a number of nodes that should be sampled to be in this compartment initially. Unset compartmens are assumed to have an initial condition of zero.

set_simulation_has_ended()[source]
set_simulation_has_not_ended()[source]
set_well_mixed(N_nodes, mean_contact_number)[source]

Define the model to run in a well-mixed system.

Parameters

  • N_nodes (int) -- Number of nodes in the system

  • mean_contact_number (int) -- Each node is assumed to be in contact with mean_contact_number other nodes at all times. These neighbors will be sampled randomly from the set of all remaining nodes every time a link transmission event happens.

simulate(tmax, return_compartments=None, sampling_dt=None, max_unsuccessful=None, sampling_callback=None, t0=0.0, stop_simulation_on_empty_network=True, custom_stop_condition=None, **kwargs)[source]

Returns values of the given compartments at the demanded time points (as a numpy.ndarray of shape (return_compartments), len(time_points). If return_compartments is None, all compartments will be returned.

Parameters

  • tmax (float) -- maximum length of the simulation

  • return_compartments (list of compartments, default = None:) -- The compartments for which to return time series. If None, all compartments will be returned.

  • sampling_dt (float, default = None) -- Temporal distance between samples of the compartment counts. If None, every change will be returned.

  • max_unsuccessful (int, default = None) -- The number of unsuccessful events after which the true total event rate will be evaluated (it might happen that a network becomes effectively disconnected while nodes are still associated with a maximum event rate). If None, this number will be set equal to the number of nodes.

  • sampling_callback (funtion, default = None) -- A function that's called when a sample is taken

Returns

  • t (numpy.ndarray) -- times at which compartment counts have been sampled

  • result (dict) -- Dictionary mapping a compartment to a time series of its count.

simulation_has_ended()[source]

Check wether the simulation can be continued in its current state.

class epipack.stochastic_epi_models.StochasticSIModel(N, infection_rate, *args, **kwargs)[source]

Bases: epipack.stochastic_epi_models.StochasticEpiModel

An SI model derived from epipack.stochastic_epi_models.StochasticEpiModel.

Parameters
compartments
[ "S", "I" ]
Type

list of str

class epipack.stochastic_epi_models.StochasticSIRModel(N, R0, recovery_rate, *args, **kwargs)[source]

Bases: epipack.stochastic_epi_models.StochasticEpiModel

An SIR model derived from epipack.stochastic_epi_models.StochasticEpiModel.

Parameters
compartments
[ "S", "I", "R" ]
Type

list of str

class epipack.stochastic_epi_models.StochasticSISModel(N, R0, recovery_rate, *args, **kwargs)[source]

Bases: epipack.stochastic_epi_models.StochasticEpiModel

An SIS model derived from epipack.stochastic_epi_models.StochasticEpiModel.

Parameters
compartments
[ "S", "I" ]
Type

list of str