Locus: Loci of disease dynamics

Loci are an abstraction of where events 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 management of loci is automated as far as possible within the procedural interface for evolving the working network within Process. Using these methods (and the methods extended in sub-classes) hopefully renders the machinery largely transparent.

class epydemic.Locus(name)

The locus of dynamics, where changes can happen. Loci are filled with nodes or edges from a network and represent some (possibly complete) sub-set of the elements, typically being populated and re-populated as a process over the network evolves.

A locus is basically a set with some additional methods to allow for more complex behaviours, including customisable drawing random selection of elements. The underlying set is implemented as a DrawSet to ensure scalability, especially of the draw() method whose performance is critical.

Parameters:

name (str) – the locus name

Locus.name()

Returns the name of the locus.

Return type:

str

Returns:

the locus’ name

Locus.setProcess(p)

Associate the locus with the given process.

Parameters:

p (Process) – the process

Locus.process()

Return the process this locus is associated with.

Return type:

Process

Returns:

the process

Handlers

There are also four methods that define the way in which changes in the network are reflected in the populations of loci.

Locus.addHandler(g, e)

Handler called when an element is added to the network. This is used to indicate the the population of nodes or edges has changed.

Parameters:

  • g (Graph) – the network

  • e (Union[Any, Tuple[Any, Any]]) – the element

Locus.leaveHandler(g, e)

Handler for when an element leaves the locus due to changes in circumstances, not changes in population.

Parameters:

  • g (Graph) – the network

  • e (Union[Any, Tuple[Any, Any]]) – the element

Locus.enterHandler(g, e)

Handler for when an element enters the locus due to changes in circumstances, not changes in population.

Parameters:

  • g (Graph) – the network

  • e (Union[Any, Tuple[Any, Any]]) – the element

Locus.removeHandler(g, e)

Handler called when an element is removed from the network. This is used to indicate the the population of nodes or edges has changed.

Parameters:

  • g (Graph) – the network

  • e (Union[Any, Tuple[Any, Any]]) – the element

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

Locus sub-classes

The main locus sub-classes are used when modelling a compartmented model of disease, to capture the nodes and edges in the various compartments where dynamics occurs. These compartments are used by CompartmentedModel.

class epydemic.CompartmentedLocus(name)

Bases: Locus

A locus based on the compartments that nodes reside in.

Parameters:

name (str) – the locus’ name

CompartmentedLocus.compartments()

Return the compartments this locus monitors. This should be overridden by sub-classes as required.

Return type:

List[str]

Returns:

the compartments

class epydemic.CompartmentedNodeLocus(name, c)

Bases: CompartmentedLocus

A locus for dynamics occurring at a single node, where the locus tracks all nodes in a single compartment.

Parameters:

  • name (str) – the locus’ name

  • c (str) – the compartment

class epydemic.CompartmentedEdgeLocus(name, l, r)

Bases: CompartmentedLocus

A locus for dynamics occurring at an edge, where the locus tracks all edges whose endpoint nodes are in specified compartments. Since the network may also be adaptive, we need to track additions and removals of edges too.

Parameters:

  • name (str) – the locus’ name

  • l (str) – the left compartment

  • r (str) – the right compartment

The compartmented edge locus extends the default handler methods.

CompartmentedEdgeLocus.matches(g, n, m)

Test whether the given edge has the right compartment endpoints for this compartment. The method returns 1 if the edge has the right compartments in the orientation (n, m), -1 if it has the right compartments in orientation (m, n), and 0 otherwise.

Parameters:

  • g (Graph) – the network

  • n (Any) – the first node

  • m (Any) – the second node

Return type:

int

Returns:

match status -1, 0, or 1

CompartmentedEdgeLocus.addHandler(g, e)

An edge is added to the network, check if its endpoint compartments match the locus and add it if so.

Param, g:

the network

Parameters:

e (Tuple[Any, Any]) – the edge

CompartmentedEdgeLocus.enterHandler(g, n)

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

Parameters:

  • g (Graph) – the network

  • n (Any) – the node

CompartmentedEdgeLocus.leaveHandler(g, n)

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

Parameters:

  • g (Graph) – the network

  • n (Any) – the node

CompartmentedEdgeLocus.removeHandler(g, e)

An edge is removed from the network, check whether it was in this locus and remove it if so.

Param, g:

the network

Parameters:

e (Tuple[Any, Any]) – the edge