CompartmentedModel
: Compartmented models of disease¶

class
epydemic.
CompartmentedModel
¶ Bases:
object
The base class for compartmented models. A compartmented model of disease represents a disease as a collection of discrete compartments, with each compartment specifying some facet of the disease’s progression. Nodes transition between compartments with some probability, so the disease’s progession is a stochastic process in which the various nodes typically move through several compartments according to the probabilities defined.
Compartmented models are designed so that their specification is independent of the process dynamics used to simulate them: they can be run in discrete time using synchronous dynamics, or in continuous time using stochastic dynamics.
CompartmentedModel
is an abstract class that must be
subclassed to define actual disease models. epydemic provides
implementations of the two “reference” compartmented models,
SIR
and SIS
, as well as several variants of them:
Hethcote provides a survey of a huge range of others.
Attributes¶

CompartmentedModel.
COMPARTMENT
= ‘dynamics_compartment’¶ Node attribute used to hold compartment.

CompartmentedModel.
OCCUPIED
= ‘occupied’¶ Edge attribute, True if edge passed infection.
Building the model¶
Building a model means specifying the various compartments, loci, and
events, and their associated probabilities. These methods are
typically called from the CompartmentedModel.build()
method,
which is called during setup to build the model using the
experiment’s simulation parameters.

CompartmentedModel.
addCompartment
(c, p=0.0)¶ Add a compartment to the model. A node is assigned to the compartment initially with the given probability. The probabilities for all compartments in the model must sum to 1.
Parameters:  c – the compartment name
 p – the initial occupancy probability (defaults to 0.0)

CompartmentedModel.
addLocus
(l, r=None, name=None)¶ Add a one or twocompartment locus, corresponding to a node or edge at which dynamics occurs (e.g,. which can have events associated with it).
Parameters:  l – the lefthand (or only) compartment
 r – the righthand compartment (for an edge)
 name – the name of the locus

CompartmentedModel.
addEvent
(l, p, ef)¶ Add a probabilistic event at a locus, occurring with a particular (fixed) probability and calling the event function when it is selected.
The event function takes the dynamics, the simulation time, the network, and the element to which the event applies (a node or an edge, which will have been selected from the event’s locus).
Parameters:  l – the locus name
 p – the event probability
 ef – the event function
Model setup¶
Immediately before being run, the model is set up by placing all the
nodes into compartments chosen randomly from the initial compartment
distribution defined by the probabilities passed to
CompartmentedModel.addCompartment()
when the compartments are
created. All edges are also marked as unoccupied.

CompartmentedModel.
setUp
(dyn, g, params)¶ Set up the initial population of nodes into compartments.
Parameters:  dyn – the dynamics
 g – the network
 params – the simulation parameters

CompartmentedModel.
initialCompartmentDistribution
()¶ Return the initial distribution of nodes to compartments. The result should be a valid distribution, with probabilities summing to one.
Returns: a list of (compartment, probability) pairs
Running the model¶
The main mechanism for running a compartmented model is to change the compartment of an individual node. This generally happens in event functions. The events are triggered according to a probability distribution that allows the dynamics to pick an event. Edges can also be marked as “occupied” by the dynamics, meaning that they were included in the spread of the disease.

CompartmentedModel.
changeCompartment
(g, n, c)¶ Change the compartment of a node. This will update all loci potentiually affected by the change.
Parameters:  g – the network
 n – the node
 c – the new compartment for the node

CompartmentedModel.
eventDistribution
(t)¶ Return the distribution of events. The result should be a valid distribution, with probabilities summing to one. The default implemnentation returns a constant distribution populated from the model parameters. Subclasses may override to, for example, provide timeevolving probabilities.
Parameters: t – the current simulation time Returns: a list of (locus, probability, event function) triples

CompartmentedModel.
markOccupied
(g, e)¶ Mark the given edge as having been occupied by the dynamics, i.e., to have been traversed in transmitting the disease.
Parameters:  g – the network
 e – the edge
Extracting basic results¶
Once an experiment is run we will need to summarise the results. How
this is done depends on the dynamics and the simulation method, but
the CompartmentedModel
class provides some basic operations that can be
used.

CompartmentedModel.
compartment
(g, c)¶ Return all the nodes currently in a particular compartment in a network.
Parameters:  g – the network
 c – the compartment
Returns: a collection of nodes

CompartmentedModel.
results
(g)¶ Create a dict of experimental results for the experiment.
Parameters: g – the network Returns: a dict of experimental results

CompartmentedModel.
skeletonise
(g)¶ Remove unoccupied edges from the network. This leaves the network consisting of only “occupied” edges that were used to transmit the infection between nodes. Note that this process means that further dynamics over the network doesn’t make sense.
Returns: the network with unoccupied edges removed