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 sub-classed 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.

Creating a model

CompartmentedModel.__init__()

Create a new compartmented model.

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 set-up 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 two-compartment locus, corresponding to a node or edge at which dynamics occurs (e.g,. which can have events associated with it).

Parameters:
  • l – the left-hand (or only) compartment
  • r – the right-hand 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. Sub-classes may override to, for example, provide time-evolving 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