tlo.methods.skeleton module

A skeleton template for disease methods.

class Skeleton(name=None, resourcefilepath=None)[source]

One line summary goes here…

If it another kind of module use base class Module

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)

  • on_hsi_alert(person_id, treatment_id) [If this is disease module]

  • report_daly_values() [If this is disease module]

Bases: tlo.core.Module







Description of parameter a







Description of property a

Class attributes:


CAUSES_OF_DEATH : {‘tlo_name_of_a_cause_of_death_in_this_module’: <tlo.methods.causes.Cause object at 0x1361f7990>}

CAUSES_OF_DISABILITY : {‘tlo_name_of_a_cause_of_disability_in_this_module’: <tlo.methods.causes.Cause object at 0x1361f4290>}

INIT_DEPENDENCIES : {‘Demography’}




Functions (defined or overridden in class Skeleton):

__init__(name=None, resourcefilepath=None)[source]

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.


name – the name to use for this module. Defaults to the concrete subclass’ name.


Read parameter values from file, if required. To access files use: Path(self.resourcefilepath) / file_name


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.


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.

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


This must send back a pd.Series or pd.DataFrame that reports on the average daly-weights that have been experienced by persons in the previous month. Only rows for alive-persons must be returned. If multiple causes in CAUSES_OF_DISABILITY are defined, a pd.DataFrame must be returned with a column corresponding to each cause (but if only one cause in CAUSES_OF_DISABILITY is defined, the pd.Series does not need to be given a specific name).

To return a value of 0.0 (fully health) for everyone, use: df = self.sim.population.props return pd.Series(index=df.index[df.is_alive],data=0.0)

on_hsi_alert(person_id, treatment_id)[source]

This is called whenever there is an HSI event commissioned by one of the other disease modules.

class Skeleton_Event(module)[source]

A skeleton class for an event

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.


Class attributes:

__annotations__ : {}

Functions (defined or overridden in class Skeleton_Event):


One line summary here

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.


module – the module that created this event


Apply this event to the population.


population – the current population

class Skeleton_LoggingEvent(module)[source]


Class attributes:

__annotations__ : {}

Functions (defined or overridden in class Skeleton_LoggingEvent):


Produce a summary of the numbers of people with respect to the action of this module. This is a regular event that can output current states of people or cumulative events since last logging event.


Apply this event to the given target.

This is a no-op; subclasses should override this method.


target – the target of the event

class HSI_Skeleton_Example_Interaction(module, person_id)[source]

This is a Health System Interaction Event. An interaction with the healthsystem are encapsulated in events like this. It must begin HSI_<Module_Name>_Description

Bases: tlo.methods.healthsystem.HSI_Event,

Functions (defined or overridden in class HSI_Skeleton_Example_Interaction):

__init__(module, person_id)[source]

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.


module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor)[source]

Do the action that take place in this health system interaction, in light of prevailing conditions in the healthcare system:

  • squeeze_factor (an argument provided to the event) indicates the extent to which this HSI_Event is being run in the context of an over-burdened healthcare facility.

  • bed_days_allocated_to_this_event (a property of the event) indicates the number and types of bed-days that have been allocated to this event.

Can return an updated APPT_FOOTPRINT if this differs from the declaration in self.EXPECTED_APPT_FOOTPRINT

To request consumables use - self.get_all_consumables(item_codes=my_item_codes)


Do any action that is necessary each time when the health system interaction is not run. This is called each day that the HSI is ‘due’ but not run due to insufficient health system capabilities. Return False to cause this HSI event not to be rescheduled and to therefore never be run. (Returning nothing or True will cause this event to be rescheduled for the next day.)


Do any action that is necessary when it is clear that the HSI event will never be run. This will occur if it has not run and the simulation date has passed the date ‘tclose’ by which the event was scheduled to have occurred. Do not return anything.