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

Set up the baseline population with TB prevalence

Bases: tlo.core.Module

PARAMETERS:

Item

Type

Description

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

prop_mdr2010

REAL

Proportion of active tb cases with multidrug resistance in 2010

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

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_ever_tested

BOOL

ever had a 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 0x7feb91146ee0>, ‘AIDS_TB’: <tlo.methods.causes.Cause object at 0x7feb91146f70>}

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

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

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

OPTIONAL_INIT_DEPENDENCIES : {‘HealthBurden’, ‘Hiv’}

SYMPTOMS : {‘night_sweats’, ‘fatigue’}

Functions (defined or overridden in class Tb):

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

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)[source]
    1. Reads the ResourceFiles

    1. Declares the DALY weights

    1. Declares the Symptoms

pre_initialise_population()[source]
  • Establish the Linear Models

send_for_screening(population)[source]
select_tb_test(person_id)[source]
get_consumables_for_dx_and_tx()[source]
initialise_population(population)[source]

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)[source]
    1. Schedule the regular TB events

    1. Schedule the Logging Event

    1. Define the DxTests and treatment options

on_birth(mother_id, child_id)[source]

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

report_daly_values()[source]

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

assign_active_tb(population, strain, incidence_rate)[source]

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

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

relapse_event(population)[source]

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

check that the properties are currently configured correctly

class ScenarioSetupEvent(module)[source]

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 optimistic, achieving all program targets * scenario 2 realistic, program constraints, tx/dx test stockouts, high dropout * scenario 3 additional measure to reduce incidence * scenario 4 SHINE trial

It only occurs once at param: scenario_start_date, called by initialise_simulation

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

Functions (defined or overridden in class ScenarioSetupEvent):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class TbActiveCasePoll(module)[source]

The Tb Regular Poll Event for assigning active infections * selects people for latent infection and schedules onset of active tb * schedules tb screening / testing

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

Functions (defined or overridden in class TbActiveCasePoll):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class TbTreatmentAndRelapseEvents(module)[source]

This event runs each month and calls two functions: * 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

Functions (defined or overridden in class TbTreatmentAndRelapseEvents):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class TbActiveEvent(module)[source]
  • 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 general population and symptomatic active cases

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

Functions (defined or overridden in class TbActiveEvent):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class TbSelfCureEvent(module)[source]

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

Functions (defined or overridden in class TbSelfCureEvent):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class HSI_Tb_ScreeningAndRefer(module, person_id, suppress_footprint=False)[source]

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.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Tb_ScreeningAndRefer):

__init__(module, person_id, suppress_footprint=False)[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.

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

Do the screening and referring to next tests

class HSI_Tb_Xray_level1b(module, person_id, suppress_footprint=False)[source]

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.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Tb_Xray_level1b):

__init__(module, person_id, suppress_footprint=False)[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.

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

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_Xray_level2(module, person_id, suppress_footprint=False)[source]

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.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Tb_Xray_level2):

__init__(module, person_id, suppress_footprint=False)[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.

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

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_StartTreatment(module, person_id)[source]

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

Functions (defined or overridden in class HSI_Tb_StartTreatment):

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

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

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

select_treatment(person_id)[source]

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

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.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Tb_FollowUp):

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

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

Apply this event to the population.

Must be implemented by subclasses.

class HSI_Tb_Start_or_Continue_Ipt(module, person_id)[source]

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.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Tb_Start_or_Continue_Ipt):

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

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

Apply this event to the population.

Must be implemented by subclasses.

class Tb_DecisionToContinueIPT(module, person_id)[source]

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)[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.

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

Apply this event to the given person.

Must be implemented by subclasses.

Parameters

person_id – the person the event happens to

class TbDeathEvent(module, person_id, cause)[source]

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)[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.

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

Apply this event to the given person.

Must be implemented by subclasses.

Parameters

person_id – the person the event happens to

class TbLoggingEvent(module)[source]

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

Functions (defined or overridden in class TbLoggingEvent):

__init__(module)[source]

produce some outputs to check

apply(population)[source]

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class TbCheckPropertiesEvent(module)[source]

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

Functions (defined or overridden in class TbCheckPropertiesEvent):

__init__(module)[source]

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

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class DummyTbModule(name=None, active_tb_prev=0.001)[source]

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

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

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

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

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

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 – the mother for this child (can be -1 if the mother is not identified).

  • child – the new child