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 wellmixed system or on a weighted, directed network. By default, the epidemiological process is considered to run in a wellmixed system.
 Parameters
compartments (
list
ofstring
)  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 wellmixed population where for each linktransmission 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 hashable types that describe each compartment, (e.g. "S", "I", etc.).

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_changes
()[source]¶ Let an event take place according to the new time and return the change in compartment counts.

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

make_node_event
(reacting_node, event, neighbor=None)[source]¶ Let a specific node event happen
 Parameters
 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.

set_conditional_link_transmission_processes
(process_dict)[source]¶ Define link transmission processes between compartments.
 Parameters
process_dict (
list
oftuple
) 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 Inode recovers (to R), scan all of the newlyrecovered 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 \(1p\).
epi.set_conditional_link_transmission_processes({ ( "I", ">", "R" ) : [ ("R", "S", ">", "R", "X" ), ("R", "I", p, "R", "Q" ), ] })

set_link_transmission_processes
(process_list)[source]¶ Define link transmission processes between compartments.
 Parameters
process_list (
list
oftuple
) 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_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
oftuple
) 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_well_mixed
(N_nodes, mean_contact_number)[source]¶ Define the model to run in a wellmixed system.

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)
. Ifreturn_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.

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
N (int)  Number of nodes.
infection_rate (float)  Inverse mean duration of a single SIcontact until infection \(\eta=1/\tau\).
*args (list)  List of arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.**kwargs (dict)  Additional keyword arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.

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
N (int)  Number of nodes.
R0 (float)  Basic reproduction number \(R_0 = \eta\left< k\right>/\rho\).
recovery_rate (float)  Inverse duration of infection \(\rho=1/\tau_I\).
*args (list)  List of arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.**kwargs (dict)  Additional keyword arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.

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
N (int)  Number of nodes.
R0 (float)  Basic reproduction number \(R_0 = \eta\left< k\right>/\rho\).
recovery_rate (float)  Inverse duration of infection \(\rho=1/\tau_I\).
*args (list)  List of arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.**kwargs (dict)  Additional keyword arguments that will be passed to
epipack.stochastic_epi_models.StochasticEpiModel
.

compartments
¶ [ "S", "I" ]
 Type
list of str