tlo.methods.tb module

This module schedules TB infection and natural history It schedules TB treatment and follow-up appointments along with preventive therapy for eligible people (HIV+ and paediatric contacts of active TB cases

class Tb(name=None, resourcefilepath=None, run_with_checks=False)

Set up the baseline population with TB prevalence

Bases: tlo.core.Module

PARAMETERS:

Item	Type	Description
prop_mdr2010	REAL	Proportion of active tb cases with multidrug resistance in 2010
who_incidence_estimates	REAL	WHO estimated active TB incidence per 100,000 population
followup_times	DATA_FRAME	times(weeks) tb treatment monitoring required after tx start
tb_high_risk_distr	LIST	list of ten high-risk districts
ipt_coverage	DATA_FRAME	national estimates of coverage of IPT in PLHIV and paediatric contacts
incidence_active_tb_2010	REAL	incidence of active tb in 2010 in all ages
rr_tb_child	REAL	relative risk of tb infection if under 16 years of age
rr_bcg_inf	REAL	relative risk of tb infection with bcg vaccination
monthly_prob_relapse_tx_complete	REAL	monthly probability of relapse once treatment complete
monthly_prob_relapse_tx_incomplete	REAL	monthly probability of relapse if treatment incomplete
monthly_prob_relapse_2yrs	REAL	monthly probability of relapse 2 years after treatment complete
rr_relapse_hiv	REAL	relative risk of relapse for HIV-positive people
scaling_factor_WHO	REAL	scaling factor applied to WHO estimates to account for the impact of interventions in place
duration_active_disease_years	REAL	duration of active disease from onset to cure or death
prop_smear_positive	REAL	proportion of new active cases that will be smear-positive
prop_smear_positive_hiv	REAL	proportion of hiv+ active tb cases that will be smear-positive
death_rate_smear_pos_untreated	REAL	probability of death in smear-positive tb cases with untreated tb
death_rate_smear_neg_untreated	REAL	probability of death in smear-negative tb cases with untreated tb
death_rate_child0_4_treated	REAL	probability of death in child aged 0-4 years with treated tb
death_rate_child5_14_treated	REAL	probability of death in child aged 5-14 years with treated tb
death_rate_adult_treated	REAL	probability of death in adult aged >=15 years with treated tb
rr_tb_bcg	REAL	relative risk of progression to active disease for children with BCG vaccine
rr_tb_hiv	REAL	relative risk of progression to active disease for PLHIV
rr_tb_aids	REAL	relative risk of progression to active disease for PLHIV with AIDS
rr_tb_art_adult	REAL	relative risk of progression to active disease for adults with HIV on ART
rr_tb_art_child	REAL	relative risk of progression to active disease for adults with HIV on ART
rr_tb_obese	REAL	relative risk of progression to active disease if obese
rr_tb_diabetes1	REAL	relative risk of progression to active disease with type 1 diabetes
rr_tb_alcohol	REAL	relative risk of progression to active disease with heavy alcohol use
rr_tb_smoking	REAL	relative risk of progression to active disease with smoking
rr_ipt_adult	REAL	relative risk of active TB with IPT in adults
rr_ipt_child	REAL	relative risk of active TB with IPT in children
rr_ipt_adult_hiv	REAL	relative risk of active TB with IPT in adults with hiv
rr_ipt_child_hiv	REAL	relative risk of active TB with IPT in children with hiv
rr_ipt_art_adult	REAL	relative risk of active TB with IPT and ART in adults
rr_ipt_art_child	REAL	relative risk of active TB with IPT and ART in children
sens_xpert_smear_negative	REAL	sensitivity of Xpert test in smear negative TB cases
sens_xpert_smear_positive	REAL	sensitivity of Xpert test in smear positive TB cases
spec_xpert_smear_negative	REAL	specificity of Xpert test in smear negative TB cases
spec_xpert_smear_positive	REAL	specificity of Xpert test in smear positive TB cases
sens_sputum_smear_positive	REAL	sensitivity of sputum smear microscopy in sputum positive cases
spec_sputum_smear_positive	REAL	specificity of sputum smear microscopy in sputum positive cases
sens_clinical	REAL	sensitivity of clinical diagnosis in detecting active TB
spec_clinical	REAL	specificity of clinical diagnosis in detecting TB
sens_xray_smear_negative	REAL	sensitivity of x-ray diagnosis in smear negative TB cases
sens_xray_smear_positive	REAL	sensitivity of x-ray diagnosis in smear positive TB cases
spec_xray_smear_negative	REAL	specificity of x-ray diagnosis in smear negative TB cases
spec_xray_smear_positive	REAL	specificity of x-ray diagnosis in smear positive TB cases
prob_tx_success_ds	REAL	Probability of treatment success for new and relapse TB cases
prob_tx_success_mdr	REAL	Probability of treatment success for MDR-TB cases
prob_tx_success_0_4	REAL	Probability of treatment success for children aged 0-4 years
prob_tx_success_5_14	REAL	Probability of treatment success for children aged 5-14 years
prob_tx_success_shorter	REAL	Probability of treatment success for children aged <16 years on shorter regimen
rate_testing_general_pop	REAL	rate of screening / testing per month in general population
rate_testing_active_tb	DATA_FRAME	rate of screening / testing per month in population with active tb
ds_treatment_length	REAL	length of treatment for drug-susceptible tb (first case) in months
ds_retreatment_length	REAL	length of treatment for drug-susceptible tb (secondary case) in months
mdr_treatment_length	REAL	length of treatment for mdr-tb in months
child_shorter_treatment_length	REAL	length of treatment for shorter paediatric regimen in months
prob_retained_ipt_6_months	REAL	probability of being retained on IPT every 6 months if still eligible
age_eligibility_for_ipt	REAL	eligibility criteria (years of age) for IPT given to contacts of TB cases
ipt_start_date	INT	year from which IPT is available for paediatric contacts of diagnosed active TB cases
scenario	INT	integer value labelling the scenario to be run: default is 0
scenario_start_date	DATE	date from which different scenarios are run
first_line_test	STRING	name of first test to be used for TB diagnosis
second_line_test	STRING	name of second test to be used for TB diagnosis
probability_access_to_xray	REAL	probability a person will have access to chest x-ray
prob_tb_referral_in_generic_hsi	REAL	probability of referral to TB screening HSI if presenting with TB-related symptoms
scaleup_parameters	DATA_FRAME	list of parameters and values changed in scenario analysis

PROPERTIES:

Item	Type	Description
tb_inf	CATEGORICAL	tb status. Possible values are: [uninfected, latent, active, ]
tb_strain	CATEGORICAL	tb strain: drug-susceptible (ds) or multi-drug resistant (mdr). Possible values are: [none, ds, mdr, ]
tb_date_latent	DATE	Date acquired tb infection (latent stage)
tb_scheduled_date_active	DATE	Date active tb is scheduled to start
tb_date_active	DATE	Date active tb started
tb_smear	BOOL	smear positivity with active infection: False=negative, True=positive
tb_date_tested	DATE	Date of last tb test
tb_diagnosed	BOOL	person has current diagnosis of active tb
tb_date_diagnosed	DATE	date most recent tb diagnosis
tb_diagnosed_mdr	BOOL	person has current diagnosis of active mdr-tb
tb_on_treatment	BOOL	on tb treatment regimen
tb_date_treated	DATE	date most recent tb treatment started
tb_treatment_regimen	CATEGORICAL	current tb treatment regimen. Possible values are: [none, tb_tx_adult, tb_tx_child, tb_tx_child_shorter, tb_retx_adult, tb_retx_child, tb_mdrtx, ]
tb_ever_treated	BOOL	if ever treated for active tb
tb_treatment_failure	BOOL	failed first line tb treatment
tb_treated_mdr	BOOL	on tb treatment MDR regimen
tb_date_treated_mdr	DATE	date tb MDR treatment started
tb_on_ipt	BOOL	if currently on ipt
tb_date_ipt	DATE	date ipt started

Class attributes:

CAUSES_OF_DEATH : {‘TB’: <tlo.methods.causes.Cause object at 0x124debf90>, ‘AIDS_TB’: <tlo.methods.causes.Cause object at 0x124deb910>}

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

INIT_DEPENDENCIES : {‘Lifestyle’, ‘HealthSystem’, ‘Epi’, ‘Demography’, ‘SymptomManager’}

METADATA : {<Metadata.USES_SYMPTOMMANAGER: 2>, <Metadata.USES_HEALTHBURDEN: 4>, <Metadata.USES_HEALTHSYSTEM: 3>, <Metadata.DISEASE_MODULE: 1>}

OPTIONAL_INIT_DEPENDENCIES : {‘Hiv’, ‘HealthBurden’}

SYMPTOMS : {‘night_sweats’, ‘fatigue’}

Functions (defined or overridden in class Tb):

__init__(name=None, resourcefilepath=None, run_with_checks=False)

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

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

Parameters:

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

read_parameters(data_folder)

• 1. Reads the ResourceFiles

• 2. Declares the DALY weights

• 3. Declares the Symptoms

pre_initialise_population()

• Establish the Linear Models

send_for_screening_general(population)

select_tb_test(person_id)

get_consumables_for_dx_and_tx()

initialise_population(population)

Set our property values for the initial population.

Must be implemented by subclasses.

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 its PROPERTIES dictionary.

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)

• 1. Schedule the regular TB events

• 2. Schedule the scenario change

• 3. Define the DxTests and treatment options

on_birth(mother_id, child_id)

Initialise properties for a newborn individual allocate IPT for child if mother diagnosed with TB

report_daly_values()

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. The names of the series of columns is taken to be the label of the cause of this disability. It will be recorded by the healthburden module as <ModuleName>_<Cause>.

calculate_untreated_proportion(population, strain)

calculate the proportion of active TB cases not on correct treatment if mdr-tb and on first-line treatment, count case as untreated they will continue to contribute to transmission

assign_active_tb(population, strain, incidence)

select individuals to be infected assign scheduled date of active tb onset update properties as needed symptoms and smear status are assigned in the TbActiveEvent

consider_ipt_for_those_initiating_art(person_id)

this is called by HIV when person is initiating ART checks whether person is eligible for IPT

relapse_event(population)

The Tb Regular Relapse Event runs every month to randomly sample amongst those previously infected with active tb * Schedules persons who have previously been infected to relapse with a set probability * Sets a scheduled_date_active which is picked up by TbActiveEvent

end_treatment(population)

• check for those eligible to finish treatment

• sample for treatment failure and refer for follow-up screening/testing

• if treatment has finished, change individual properties

check_config_of_properties()

check that the properties are currently configured correctly

class ScenarioSetupEvent(module)

This event exists to change parameters or functions depending on the scenario for projections which has been set * scenario 0 is the default which uses baseline parameters * scenario 1 achieves all program targets with consumables constraints * scenario 2 achieves all program targets without consumables constraints It only occurs once at param: scenario_start_date, called by initialise_simulation

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class ScenarioSetupEvent):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class TbActiveCasePoll(module)

The Tb Regular Poll Event for assigning active infections * selects people for active infection and schedules onset of active tb assign_active_tb uses a transmission model to assign new cases import_tb simulates importation of active tb independent of current prevalence

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbActiveCasePoll):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class TbTreatmentAndRelapseEvents(module)

This event runs each month and calls three functions: * scheduling TB screening for the general population * ending treatment if end of treatment regimen has been reached * determining who will relapse after a primary infection

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbTreatmentAndRelapseEvents):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class TbActiveEvent(module)

• check for those with dates of active tb onset within last time-period

*1 change individual properties for active disease *2 assign symptoms *3 if HIV+, assign smear status and schedule AIDS onset *4 if HIV-, assign smear status and schedule death *5 schedule screening for symptomatic active cases

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbActiveEvent):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class TbSelfCureEvent(module)

annual event which allows some individuals to self-cure approximate time from infection to self-cure is 3 years HIV+ and not virally suppressed cannot self-cure note that frequency can’t be changed here as parameters are set to annual values

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbSelfCureEvent):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class HSI_Tb_ScreeningAndRefer(module, person_id, suppress_footprint=False)

The is the Screening-and-Refer HSI. A positive outcome from symptom-based screening will prompt referral to tb tests (sputum/xpert/xray) no consumables are required for screening (4 clinical questions)

This event is scheduled by:

• the main event poll,

• when someone presents for care through a Generic HSI with tb-like symptoms

• active screening / contact tracing programmes

If this event is called within another HSI, it may be desirable to limit the functionality of the HSI: do this using the arguments:

• suppress_footprint=True : the HSI will not have any footprint

This event will: * screen individuals for TB symptoms * administer appropriate TB test * schedule treatment if needed * give IPT for paediatric contacts of diagnosed case

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_ScreeningAndRefer):

__init__(module, person_id, suppress_footprint=False)

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.

Parameters:

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)

Do the screening and referring to next tests

class HSI_Tb_ClinicalDiagnosis(module, person_id, suppress_footprint=False)

This is a clinical diagnosis appt which is called when other tests have not been available and only a clinical diagnosis is required

• it does not include any of the routine tests for TB or HIV

therefore property tb_date_tested is not updated * It only requires 0.5 footprint of Under5OPD since it will almost exclusively be used for children unable to get xrays following initial diagnostic consultations

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_ClinicalDiagnosis):

__init__(module, person_id, suppress_footprint=False)

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.

Parameters:

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)

Do the screening and referring process

class HSI_Tb_Xray_level1b(module, person_id, suppress_footprint=False)

The is the x-ray HSI usually used for testing children unable to produce sputum positive result will prompt referral to start treatment

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_Xray_level1b):

__init__(module, person_id, suppress_footprint=False)

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.

Parameters:

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)

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_Xray_level2(module, person_id, suppress_footprint=False)

The is the x-ray HSI performed at level 2 usually used for testing children unable to produce sputum positive result will prompt referral to start treatment

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_Xray_level2):

__init__(module, person_id, suppress_footprint=False)

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.

Parameters:

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)

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_StartTreatment(module, person_id)

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

EXPECTED_APPT_FOOTPRINT : <property object at 0x124ad7f10>

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_StartTreatment):

__init__(module, person_id)

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.

Parameters:

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)

This is a Health System Interaction Event - start TB treatment select appropriate treatment and request if available, change person’s properties

post_apply_hook()

Impose the bed-days footprint (if target of the HSI is a person_id)

select_treatment(person_id)

helper function to select appropriate treatment and check whether consumables are available to start drug course treatment will always be for ds-tb unless mdr has been identified :return: drug_available [BOOL]

class HSI_Tb_FollowUp(module, person_id)

This is a Health System Interaction Event clinical monitoring for tb patients on treatment will schedule sputum smear test if needed if positive sputum smear, schedule xpert test for drug sensitivity then schedule the next follow-up appt if needed

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_FollowUp):

__init__(module, person_id)

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.

Parameters:

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)

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_Start_or_Continue_Ipt(module, person_id)

This is a Health System Interaction Event - give ipt to reduce risk of active TB It can be scheduled by: * HIV.HSI_Hiv_StartOrContinueTreatment for PLHIV, diagnosed and on ART * Tb.HSI_Tb_StartTreatment for up to 5 contacts of diagnosed active TB case

if person referred by ART initiation (HIV+), IPT given for 36 months paediatric IPT is 6-9 months

Bases: tlo.methods.hsi_event.HSI_Event, tlo.events.IndividualScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class HSI_Tb_Start_or_Continue_Ipt):

__init__(module, person_id)

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.

Parameters:

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)

Apply this event to the population.

Must be implemented by subclasses.

class Tb_DecisionToContinueIPT(module, person_id)

Helper event that is used to ‘decide’ if someone on IPT should continue or end This event is scheduled by ‘HSI_Tb_Start_or_Continue_Ipt’ after 6 months

• end IPT for all

• schedule further IPT for HIV+ if still eligible (no active TB diagnosed, <36 months IPT)

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class Tb_DecisionToContinueIPT):

__init__(module, person_id)

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.

Parameters:

• 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.

• priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class TbDeathEvent(module, person_id, cause)

The scheduled death for a tb case check whether this death should occur using a linear model will depend on treatment status, smear status and age

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class TbDeathEvent):

__init__(module, person_id, cause)

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.

Parameters:

• 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.

• priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class TbLoggingEvent(module)

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbLoggingEvent):

__init__(module)

produce some outputs to check

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class TbCheckPropertiesEvent(module)

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class TbCheckPropertiesEvent):

__init__(module)

Create a new regular event.

Parameters:

• module – the module that created this event

• frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)

Apply this event to the given target.

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

Parameters:

target – the target of the event

class DummyTbModule(name=None, active_tb_prev=0.001)

Dummy TB Module - it’s only job is to create and maintain the ‘tb_inf’ property. This can be used in test files.

Bases: tlo.core.Module

PROPERTIES:

Item	Type	Description
tb_inf	CATEGORICAL	tb status. Possible values are: [uninfected, latent, active, ]

Class attributes:

ALTERNATIVE_TO : {‘Tb’}

INIT_DEPENDENCIES : {‘Demography’}

Functions (defined or overridden in class DummyTbModule):

__init__(name=None, active_tb_prev=0.001)

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

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

Parameters:

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

read_parameters(data_folder)

Read parameter values from file, if required.

Must be implemented by subclasses.

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.

Must be implemented by subclasses.

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 its PROPERTIES dictionary.

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.

Must be implemented by subclasses.

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, child)

Initialise our properties for a newborn individual.

Must be implemented by subclasses.

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

Parameters:

• mother_id – the person id for the mother of this child (can be -1 if the mother is not identified).

• child_id – the person id of new child