# Locus: Loci of disease dynamics¶

Loci are an abstraction of where disease happens within a model. The dynamics of a model defines what events are called; the loci define the population of nodes or edges that may be subject to a particular event. The CompartmentedModel class keeps track of these populations automatically from the definition of a model.

There will seldom be any need to understand (or even interact with) loci except if, for example, defining new dynamics. For building and operating model simulations, loci are transparent for the programmer.

## Locus: The base class¶

class epydemic.Locus(name)

Bases: object

The locus of dynamics. A locus is where dynamics happens, allowing the compartments of nodes to be changed and other effects to be coded-up. Loci are filled with nodes or edges, typically populated and re-populated as the dynamics moves nodes between components.

Locus.name()

Returns the name of the locus.

Returns: the locus’ name

There are three main access methods defined on loci: to get the length of the locus (the number of nodes or edges it contains); to retrieve the elements themselves; and to draw one element at random.

Locus.__len__()

Return the number of elements at the locus.

Returns: the number of elements
Locus.elements()

Return the underlying elements of the locus.

Returns: the elements
Locus.draw()

Draw a random element from the locus. The locus is left unchanged.

Returns: a random element at the locus

There are also two abstract methods that define the way in which changes in node compartments are reflected in the populations of loci.

Locus.leaveHandler(m, g, n, c)

Handler for when a node leaves a compartment., Must be overridden by sub-classes.

Parameters: m – the model g – the network n – the node c – the compartment the node is leaving
Locus.enterHandler(m, g, n, c)

Handler for when a node enters a compartment., Must be overridden by sub-classes.

Parameters: m – the model g – the network n – the node c – the compartment the node is entering

It is these methods that are overridden in sub-classes to provide the behaviour of node and edge loci.

## NodeLocus: Loci for node-level dynamics¶

class epydemic.NodeLocus(name, c)

Bases: epydemic.loci.Locus

A locus for dynamics occurring at a single node. Node loci contain nodes, typically all in a single compartment.

NodeLocus.__init__(name, c)

Create a locus for nodes in the given compartment.

Parameters: name – the locus’ name c – the compartment
NodeLocus.leaveHandler(m, g, n, c)

Node leaves the right compartment, remove it from the locus

Parameters: m – the model g – the network n – the node c – the compartment the node is leavinging
NodeLocus.enterHandler(m, g, n, c)

Node enters the right compartment, add it to the locus

Parameters: m – the model g – the network n – the node c – the compartment the node is entering

## EdgeLocus: Loci for edge-level dynamics¶

class epydemic.EdgeLocus(name, l, r)

Bases: epydemic.loci.Locus

A locus for dynamics occurring at an edge. Edge loci contain edges, typically with the endpoint nodes in different compartments. The edges within a locus change as nodes move between compartments.

EdgeLocus.__init__(name, l, r)

Create a locus for an edge with endpoints in the given compartments. Edges are treated as directed, in the sense that the edge will always be manipulated according to the given orientation.

Parameters: name – the locus’ name l – the left compartment r – the right compartment
EdgeLocus.leaveHandler(m, g, n, c)

Node leaves one of the edge’s compartments, remove any incident edges that no longer have the correct orientation.

Parameters: m – the model g – the network n – the node c – the compartment the node is leaving
EdgeLocus.enterHandler(m, g, n, c)

Node enters one of the edge’s compartments, add any incident edges that now have the correct orientation.

Parameters: m – the model g – the network n – the node c – the compartment the node is entering