Notes on declaring CAUSES_OF_DEATH and CAUSES_OF_DISABILITY

Background

Each disease module can cause two outcomes: death and disability.

We need to:

1. Identify where a cause contributes to both disability and death;
2. Identify where several modules are generating what should be considered to be the same cause of deaths or disability;
3. Identify which causes of death/disability in the GBD dataset correspond to the causes that are being represented in a disease module.

By doing this, we will be able to:

• Produce internally-consistent measures of deaths and DALYS
• Produce summaries that comparable with the GBD datasets;
• Automatically adjust the 'OtherDeathPoll' (which represents deaths from causes other those represented by the disease modules included in a simulation).

Whilst we need to enforce a coherence between disease modules, it remains acceptable (desirable, in fact!) for different disease modules to represent the effects with differing degrees of granularity. We have aimed to develop a system that is sufficiently flexible allow for that and also to require a minimum of changes in each disease module. [Note: these changes have already made for all modules in master.]

Approach

The name of causes of death and disability used in each module remain unchanged: we call these names "tlo causes". But, now, each module must "explain" what is meant by these causes. This becomes a bit complicated because:

• Some modules are responsible for many different causes of death whilst others modules are responsible for only one.
• In some cases, two modules are responsible for the same cause of death or disability.
• Many disease/condition can cause disability and death and whilst it is natural to define these somewhat differently, a line must be drawn between certain causes of death and disability for the computation of DALYS (which derive from the sum of years lived with disability and life years lost).
• The mapping between the causes defined in the module and causes in the GBD is, in principle at least, "many-to-many": i.e. some causes of death in the model map to many different causes in the GBD dataset (e.g. 'OtherCancerDeath' --> many different specific causes of cancer in GBD); whilst in other modules many different causes of death are defined which map to a single cause in the GBD data (e.g. a lot of different outcomes in pregnancy map --> 'Maternal Outcomes' in the GBD data).

Therefore, we must define, for each cause of death or disability used in the model, ("tlo_causes"):

• a "label": this the category to which the cause of death or disability belongs: It has two purposes:

  • it attaches multiple "tlo causes" of death defined in the model, or multiple causes of disability defined in the model. i.e., multiple different "tlo causes" (from within one or more modules) can be aggregated under a unifying label.
  • it attaches causes of death defined in the model with causes of disability defined in the model: i.e., causes of death and causes of disability with the same label both contribute to the DALYs with that label.

• the "gbd_causes": this is the set of strings of causes (in the GBD dataset), to which the cause of death/disability corresponds. (Look at any GBD file, e.g. ResourceFile_Deaths_And_Causes_DeathRates_GBD.csv. We using GBD's "level 3" causes.)

Important Notes

• The declared names of 'tlo_causes' of death are assumed to be UNIQUE; similarly, the declare names of 'tlo_causes' of disability are assumed to be unique.

  • If more than one module declares a tlo_cause of death/disability with the same name, the definitions of each must be identical (an AssertionError is thrown otherwise).
  • When two modules declare a tlo_cause of death/disability with the same name, these are combined together.

• A gbd_cause (a cause of death or disability defined define by the GBD) cannot be associated with more than one label. (An AssertionError is thrown otherwise). This is because in the calibration procedures gbd_causes must map many-to-one to labels.

• The gbd_causes of death defined among all the 'tlo_causes' declared in a simulation are removed as potential causes of death in the OtherDeathPoll in Demography.

• Checks during the simulation are made as follows:

  • A death caused by a module must have its 'tlo_cause' declared by that module.
  • The report_dalys function of a disease module must return a pd.DataFrame with one column named for each 'cause of disability' that is declared. (Optionally, if only one 'cause of disability' is defined by a module, then it's report_dalys function can return a pd.Series (for which the name need not be specified).

Syntax

Each disease module (identified by m.DISEASE_MODULE in the module's metadata) must declare it's CAUSES_OF_DEATH and CAUSES_OF_DISABILITY thusly:

    # Declare Causes of Death
    CAUSES_OF_DEATH = {
        'tlo_name_of_each_cause_of_death_in_this_module':
            Cause(gbd_causes={'set_of_strings_of_gbd_causes_to_which_this_cause_corresponds'},
                  label='the_category_of_which_this_cause_is_a_part')
    }

    # Declare Causes of Disability
    CAUSES_OF_DISABILITY = {
        'tlo_name_of_each_cause_of_disability_in_this_module':
            Cause(gbd_causes={'set_of_strings_of_gbd_causes_to_which_this_cause_corresponds'},
                  label='the_category_of_which_this_cause_is_a_part')
    }

Note that this is using the Cause data structure defined in tlo.core, so you will need from tlo.core import Cause.

Examples

The most simple example:

    # Declare Causes of Death
    CAUSES_OF_DEATH = {
        'BladderCancer': Cause(gbd_causes='Bladder cancer', label='Cancer'),
    }

    # Declare Causes of Disability
    CAUSES_OF_DISABILITY = {
        'BladderCancer': Cause(gbd_causes='Bladder cancer', label='Cancer'),
    }

A more complicated example:

    # Declare Causes of Death
    CAUSES_OF_DEATH = {
        'diabetes': Cause(
            gbd_causes={'Diabetes mellitus'}, label='Diabetes'),
        'chronic_ischemic_hd': Cause(
            gbd_causes={'Ischemic heart disease', 'Hypertensive heart disease'}, label='Heart Disease'),
        'heart_attack': Cause(
            gbd_causes={'Ischemic heart disease', 'Hypertensive heart disease'}, label='Heart Disease'),
        'stroke': Cause(
            gbd_causes={'Stroke'}, label='Stroke'),
        'chronic_kidney_disease': Cause(
            gbd_causes={'Chronic kidney disease'}, label='Kidney Disease')
    }

Usage

As before, the deaths (by the cause provided by the module) and disability (by the cause provided by the module) are found in the logged output as follows:

• Deaths: ['tlo.methods.demography']['deaths']: each row is a death, and the column 'cause' gives the 'tlo_cause' that is passed by the disease module.
• Years Life Lost: [tlo.methods.healtburden]['yll_by_causes_of_death'] : This is a table (by sex, age-group and year) of the years of live lost by the 'tlo_cause' of death that are used by the disease module.
• Years Lived with Disability [tlo.methods.healtburden]['yld_by_causes_of_disability'] : This is a table (by sex, age-group and year) of the years of lived with disability by the 'tlo_cause' of disability that are used by the disease module.

But now, also output are:

• DALYS: [tlo.methods.healtburden]['dalys'] : these are the sum of 'Years Life Lost' and 'Years Lived With Disability' that have the same label, broken down by year, sex, age-group'.
• Each death recorded ['tlo.methods.demography']['deaths'] is associated with the corresponding label.
• dicts that can be used to recode deaths and disability causes in GBD data into a form that is comparable with output from the model. (Note that this recoding is specific to a simulation because the 'gbd_causes' that are associated under a label is defined by the disease modules, including the GBD causes of death that are combined under the 'Other' label used in the OtherDeathPoll).
  • ['tlo.methods.demography']['mapper_from_tlo_cause_to_common_label']
  • ['tlo.methods.demography']['mapper_from_gbd_cause_to_common_label']