tlo.test.random_death module

A simple test module for demonstration purposes.

It polls the population each month, randomly killing people with a fixed probability. The probability may be set as a module parameter.

This is thus mainly useful for demonstrating how to write a disease module, without getting distracted by modelling details.

class RandomDeath(*args, **kwargs)

Bases: Module

Randomly kill individuals with fixed probability.

All disease modules need to be implemented as a class inheriting from Module. They need to provide several methods which will be called by the simulation framework: * read_parameters(data_folder) * initialise_population(population) * initialise_simulation(sim) * on_birth(mother, child)

Constructor: create an instance of this module.

This method can usually be omitted, but may be a useful place to set up module-level state that isn’t appropriate to put elsewhere. Constructor arguments can be supplied when the module is instantiated.

Here we do nothing, except that we must call the base class constructor using super(). Alternatively, we could omit the method entirely here, and just the base class constructor would be used.

Parameters:

  • args – list of positional arguments

  • kwargs – dict of keyword arguments

PARAMETERS: Dict[str, Parameter] = {'death_probability': REAL === Fixed probability of death each month}
PROPERTIES: Dict[str, Property] = {'date_of_death': DATE === When the individual died (if they have), 'is_alive': BOOL === Whether each individual is currently alive}
read_parameters(data_folder)

Read parameter values from file, if required.

Here we do nothing.

Parameters:

data_folder – path of a folder supplied to the Simulation containing data files. Typically modules would read a particular file within here.

initialise_population(population)

Set our property values for the initial population.

This method is called by the simulation when creating the initial population, and is responsible for assigning initial values, for every individual, of those properties ‘owned’ by this module, i.e. those declared in the PROPERTIES dictionary above.

TODO: We probably need to declare somehow which properties we ‘read’ here, so the simulation knows what order to initialise modules in!

Parameters:

population – the population of individuals

initialise_simulation(sim)

Get ready for simulation start.

This method is called just before the main simulation loop begins, and after all modules have read their parameters and the initial population has been created. It is a good place to add initial events to the event queue.

Here we add our monthly event to poll the population for deaths.

on_birth(mother_id, child_id)

Initialise our properties for a newborn individual.

This is called by the simulation whenever a new person is born.

Parameters:

  • mother_id – the mother for this child

  • child_id – the new child

parameters
class RandomDeathEvent(module, death_probability)

Bases: RegularEvent, PopulationScopeEventMixin

The regular event that actually kills people.

Regular events automatically reschedule themselves at a fixed frequency, and thus implement discrete timestep type behaviour. The frequency is specified when calling the base class constructor in our __init__ method.

Create a new random death event.

We need to pass the frequency at which we want to occur to the base class constructor using super(). We also pass the module that created this event, so that random number generators can be scoped per-module.

Parameters:

  • module – the module that created this event

  • death_probability – the per-person probability of death each month

apply(population)

Apply this event to the population.

For efficiency, we use pandas operations to scan the entire population and kill individuals at random.

Parameters:

population – the current population