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)[source]

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)

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

Read parameter values from file, if required.

Here we do nothing.


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


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!


population – the population of individuals


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)[source]

Initialise our properties for a newborn individual.

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

  • mother_id – the mother for this child

  • child_id – the new child

class RandomDeathEvent(module, death_probability)[source]

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.


Apply this event to the population.

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


population – the current population