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

The core demography module.

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

district_num_of_residence

INT

The district number in which the person is resident

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_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 : defaultdict(<function create_age_range_lookup.<locals>.<lambda> at 0x7feb91074040>, {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’})

Functions (defined or overridden in class Demography):

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

Parameters

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

read_parameters(data_folder)[source]

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

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

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

initialise_simulation(sim)[source]
  • Schedule the AgeUpdateEvent, the OtherDeathPoll and the DemographyLoggingEvent

  • Output to the log the initial population scaling factor.

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

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.

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

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.

get_gbd_causes_of_death_not_represented_in_disease_modules(causes_of_death)[source]

Find the causes of death in the GBD datasets that are not represented within the causes of death defined in the modules registered in this simulation. :return: set of gbd_causes of death that are not represented in disease modules

create_mappers_from_causes_of_death_to_label()[source]

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

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

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

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

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

Functions (defined or overridden in class AgeUpdateEvent):

__init__(module, age_range_lookup)[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 OtherDeathPoll(module)[source]

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.

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

Functions (defined or overridden in class OtherDeathPoll):

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

get_mort_risk_per_poll()[source]

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

Compute the all-cause risk of death per poll

get_proportion_of_deaths_to_represent_as_other_deaths()[source]

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

apply(population)[source]

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

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.

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

Functions (defined or overridden in class InstantaneousDeath):

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

Apply this event to the given person.

Must be implemented by subclasses.

Parameters

person_id – the person the event happens to

class DemographyLoggingEvent(module)[source]

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

Functions (defined or overridden in class DemographyLoggingEvent):

__init__(module)[source]

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

apply(population)[source]

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population