tlo.methods.demography module

The core demography module and its associated events. * Sets initial population size * Determines the ‘is_alive’, age-related, and residential location properties. * Runs the OtherDeathPoll which represents the deaths due to causes other than those represented by disease modules.

class Demography(name=None, resourcefilepath=None, equal_allocation_by_district: bool = False)

The core demography module.

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.

Bases: tlo.core.Module

PARAMETERS:

Item	Type	Description
max_age_initial	INT	The oldest age (in whole years) in the initial population
pop_2010	DATA_FRAME	Population in 2010 for initialising population
district_num_to_district_name	DICT	Mapping from district_num to district name
district_num_to_region_name	DICT	Mapping from district_num to region name
districts_in_region	DICT	Set of districts (by name) that are within a region (by name)
all_cause_mortality_schedule	DATA_FRAME	All-cause age-specific mortality rates from WPP
fraction_of_births_male	REAL	Birth Sex Ratio
gbd_causes_of_death_data	DATA_FRAME	Proportion of deaths in each age/sex group attributable to each possible cause of death in the GBD dataset.

PROPERTIES:

Item	Type	Description
is_alive	BOOL	Whether this individual is alive
date_of_birth	DATE	Date of birth of this individual
date_of_death	DATE	Date of death of this individual
sex	CATEGORICAL	Male or female. Possible values are: [M, F, ]
mother_id	INT	Unique identifier of mother of this individual
cause_of_death	CATEGORICAL	The cause of death of this individual (the tlo_cause defined by the module). Possible values are: [SET_AT_RUNTIME, ]
district_num_of_residence	CATEGORICAL	The district number in which the person is resident. Possible values are: [SET_AT_RUNTIME, ]
district_of_residence	CATEGORICAL	The district (name) of residence (mapped from district_num_of_residence).. Possible values are: [SET_AT_RUNTIME, ]
region_of_residence	CATEGORICAL	The region of residence (mapped from district_num_of_residence).. Possible values are: [SET_AT_RUNTIME, ]
age_exact_years	REAL	The age of the individual in exact years
age_years	INT	The age of the individual in years
age_range	CATEGORICAL	The age range category of the individual. Possible values are: [0-4, 5-9, 10-14, 15-19, 20-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90-94, 95-99, 100+, ]
age_days	INT	The age of the individual in whole days

Class attributes:

AGE_RANGE_CATEGORIES : [‘0-4’, ‘5-9’, ‘10-14’, ‘15-19’, ‘20-24’, ‘25-29’, ‘30-34’, ‘35-39’, ‘40-44’, ‘45-49’, ‘50-54’, ‘55-59’, ‘60-64’, ‘65-69’, ‘70-74’, ‘75-79’, ‘80-84’, ‘85-89’, ‘90-94’, ‘95-99’, ‘100+’]

AGE_RANGE_LOOKUP : {0: ‘0-4’, 1: ‘0-4’, 2: ‘0-4’, 3: ‘0-4’, 4: ‘0-4’, 5: ‘5-9’, 6: ‘5-9’, 7: ‘5-9’, 8: ‘5-9’, 9: ‘5-9’, 10: ‘10-14’, 11: ‘10-14’, 12: ‘10-14’, 13: ‘10-14’, 14: ‘10-14’, 15: ‘15-19’, 16: ‘15-19’, 17: ‘15-19’, 18: ‘15-19’, 19: ‘15-19’, 20: ‘20-24’, 21: ‘20-24’, 22: ‘20-24’, 23: ‘20-24’, 24: ‘20-24’, 25: ‘25-29’, 26: ‘25-29’, 27: ‘25-29’, 28: ‘25-29’, 29: ‘25-29’, 30: ‘30-34’, 31: ‘30-34’, 32: ‘30-34’, 33: ‘30-34’, 34: ‘30-34’, 35: ‘35-39’, 36: ‘35-39’, 37: ‘35-39’, 38: ‘35-39’, 39: ‘35-39’, 40: ‘40-44’, 41: ‘40-44’, 42: ‘40-44’, 43: ‘40-44’, 44: ‘40-44’, 45: ‘45-49’, 46: ‘45-49’, 47: ‘45-49’, 48: ‘45-49’, 49: ‘45-49’, 50: ‘50-54’, 51: ‘50-54’, 52: ‘50-54’, 53: ‘50-54’, 54: ‘50-54’, 55: ‘55-59’, 56: ‘55-59’, 57: ‘55-59’, 58: ‘55-59’, 59: ‘55-59’, 60: ‘60-64’, 61: ‘60-64’, 62: ‘60-64’, 63: ‘60-64’, 64: ‘60-64’, 65: ‘65-69’, 66: ‘65-69’, 67: ‘65-69’, 68: ‘65-69’, 69: ‘65-69’, 70: ‘70-74’, 71: ‘70-74’, 72: ‘70-74’, 73: ‘70-74’, 74: ‘70-74’, 75: ‘75-79’, 76: ‘75-79’, 77: ‘75-79’, 78: ‘75-79’, 79: ‘75-79’, 80: ‘80-84’, 81: ‘80-84’, 82: ‘80-84’, 83: ‘80-84’, 84: ‘80-84’, 85: ‘85-89’, 86: ‘85-89’, 87: ‘85-89’, 88: ‘85-89’, 89: ‘85-89’, 90: ‘90-94’, 91: ‘90-94’, 92: ‘90-94’, 93: ‘90-94’, 94: ‘90-94’, 95: ‘95-99’, 96: ‘95-99’, 97: ‘95-99’, 98: ‘95-99’, 99: ‘95-99’}

OPTIONAL_INIT_DEPENDENCIES : {‘ImprovedHealthSystemAndCareSeekingScenarioSwitcher’}

__annotations__ : {}

Functions (defined or overridden in class Demography):

__init__(name=None, resourcefilepath=None, equal_allocation_by_district: bool = 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)

Load the parameters from ResourceFile_Demography_parameters.csv and data from other ResourceFiles.

pre_initialise_population()

1. Store all the cause of death represented in the imported GBD data

2. Process the declarations of causes of death made by the disease modules

3. Define categorical properties for ‘cause_of_death’, ‘region_of_residence’ and ‘district_of_residence’

initialise_population(population)

Set properties for this module and compute the initial population scaling factor

initialise_simulation(sim)

• Schedule the AgeUpdateEvent, the OtherDeathPoll and the DemographyLoggingEvent

• Output to the log the initial population scaling factor.

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. :param mother_id: the mother for this child :param child_id: the new child

_edit_init_pop_to_prevent_persons_greater_than_max_age(df, max_age: int)

Return an edited version of the pd.DataFrame describing the probability of persons in the population being created with certain characteristics to reflect the constraint the persons aged greater than max_age_initial should not be created.

static _edit_init_pop_so_that_equal_number_in_each_district(df) → DataFrame

Return an edited version of the pd.DataFrame describing the probability of persons in the population being created with certain characteristics to reflect the constraint of there being an equal number of persons in each district.

process_causes_of_death()

1. Register all causes of deaths defined by Module

2. Define the “Other” causes of death (that is managed in this module by the OtherDeathPoll)

3. Output to the log mappers for causes of death (tlo_cause –> label; gbd_cause –> label).

do_death(individual_id: int, cause: str, originating_module: Module)

Register and log the death of an individual from a specific cause. * ‘individual_id’ is the index in the population.props dataframe to the (one) person. * ‘cause’ is the “tlo cause” that is defined by the disease module. * ‘originating_module’ is the disease module that is causing the death.

create_mappers_from_causes_of_death_to_label()

Use a helper function to create mappers for causes of death to label.

calc_py_lived_in_last_year(delta=<DateOffset: years=1>, mask=None)

This is a helper method to compute the person-years that were lived in the previous year by age. It outputs a pd.DataFrame with the index being single year of age, 0 to 99.

compute_initial_model_to_data_popsize_ratio(initial_population_size)

Compute ratio of initial model population size to estimated population size in 2010.

Uses the total of the per-region estimated populations in 2010 used to initialise the simulation population as the baseline figure, with this value corresponding to the 2010 projected population from [wpp2019].

[wpp2019]

World Population Prospects 2019. United Nations Department of

Economic and Social Affairs. URL: https://population.un.org/wpp/Download/Standard/Population/

Parameters:

initial_population_size – Initial population size to calculate ratio for.

Returns:

Ratio of initial_population to 2010 baseline population.

class AgeUpdateEvent(module, age_range_lookup)

This event updates the age_exact_years, age_years and age_range columns for the population based on the current simulation date

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)

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class AgeUpdateEvent):

__init__(module, age_range_lookup)

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 OtherDeathPoll(module)

This event causes deaths to persons from cause that are _not_ being modelled explicitly by a disease module. It does this by computing the GBD death rates that are implied by all the causes of death other than those that are represented in the disease module registered in this simulation.

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)

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class OtherDeathPoll):

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

get_mort_risk_per_poll()

Compute the death-rates to use (i.e., those from causes of death defined in self.causes_to_represent). This is based on using the WPP schedule for all-cause deaths and scaling by the proportion of deaths caused by those caused defined in self.causes_to_represent (as per the latest available GBD data). These mortality rates are used to compute a risk of death per person per occurrence of the polling event.

get_all_cause_mort_risk_per_poll()

Compute the all-cause risk of death per poll

get_proportion_of_deaths_to_represent_as_other_deaths()

Compute the fraction of deaths that will be reprsented by the OtherDeathPoll

apply(population)

Randomly select some persons to die of the ‘Other’ tlo cause (the causes of death that are not represented by the disease modules).

class InstantaneousDeath(module, individual_id, cause)

Call the do_death function to cause the person to die.

Note that no checking is done here. (Checking is done within do_death which can also be called directly.)

The ‘individual_id’ is the index in the population.props dataframe. It is for _one_ person only. The ‘cause’ is the cause that is defined by the disease module (aka, “tlo cause”). The ‘module’ passed to this event is the disease module that is causing the death.

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)

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

Functions (defined or overridden in class InstantaneousDeath):

__init__(module, individual_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(individual_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class DemographyLoggingEvent(module)

Logging event running every year. * Update internal storage of population size * Output statistics to the log

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class DemographyLoggingEvent):

__init__(module)

Logging event running every year. * Update internal storage of population size * Output statistics to the log

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