The Core Mortality Model

The mortality component models all-cause mortality and allows for disease models to contribute cause-specific mortality. At each time step, the currently-alive population is subjected to a mortality event using the mortality rate to determine probabilities of death for each simulant.

A weighted probable cause of death is used to choose the cause of death. The years of life lost are calculated by subtracting a simulant’s age from the population TMRLE and the population is updated.

ACMR is read from the artifact (GBD). At setup cause-specific mortality is initialized to an empty table. As disease models are registered, they affect CSMR by means of the cause_specific_mortality_rate pipeline. This is population level data.

If there are causes of death which are unmodeled, but may be impacted by some modeled entity, they can be specified using the configuration key “unmodeled_causes”.

The mortality component’s mortality_rate pipeline reflects the cause-deleted mortality rate (ACMR - CSMR). Then the impact of unmodeled causes on mortality is calculated, by subtracting the raw unmodeled CSMR before adding back the modified unmodeled CSMR.

class vivarium_public_health.population.mortality.Mortality

Model mortality in a population.

This component models all-cause mortality and allows for disease models to contribute cause-specific mortality. Data used by this class should be supplied in the artifact and is configurable in the configuration to build lookup tables. For instance, let’s say we want to use sex and hair color to build a lookup table for all cause mortality.

configuration:
    mortality:
        all_cause_mortality_rate:
            categorical_columns: ["sex", "hair_color"]

Similarly, we can do the same thing for unmodeled causes. Here is an example:

configuration:
    mortality:
        unmodeled_cause_specific_mortality_rate:
            unmodeled_causes: ["maternal_disorders", maternal_hemorrhage]
            categorical_columns: ["sex", "hair_color"]

Or if we wanted to make the data a scalar value for all cause mortality rate we could configure that as well.

configuration:
    mortality:
        data_sources:
            all_cause_mortality_rate: 0.01

property configuration_defaults: dict[str, Any]

The default configuration values for this component.

Configuration structure:

mortality:
    data_sources:
        all_cause_mortality_rate:
            Source for all-cause mortality rate data. Default is
            the artifact key
            ``cause.all_causes.cause_specific_mortality_rate``.
            This represents the background mortality rate from
            all causes combined.
        unmodeled_cause_specific_mortality_rate:
            Source for unmodeled CSMR data. Default uses the
            ``load_unmodeled_csmr`` method which sums CSMRs for
            all causes listed in ``unmodeled_causes``.
        life_expectancy:
            Source for life expectancy data. Default is the
            artifact key
            ``population.theoretical_minimum_risk_life_expectancy``.
            Used to calculate :term:`years of life lost <Years of Life Lost>` (YLLs).
    unmodeled_causes: list[str]
        List of cause names that are not explicitly modeled but
        may be affected by modeled risks. Their CSMRs are
        combined into a single pipeline that can be modified.
        Default is an empty list.

property standard_lookup_tables: list[str]

The names of lookup tables built automatically by the framework.

property time_step_priority: int

The time step priority for mortality processing.

It is set to 0 to ensure that mortality is processed before other components that may depend on simulants being alive.

setup(builder)

Set up the component by registering pipelines, lookup tables, and the population initializer.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

get_randomness_stream(builder)

Get the randomness stream used for stochastic mortality events.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

RandomnessStream

Returns:

The RandomnessStream used for filtering deaths and choosing cause of death.

register_cause_specific_mortality_rate(builder)

Register the cause-specific mortality rate attribute pipeline.

Creates an attribute producer for the cause_specific_mortality_rate pipeline initialized to zero. Disease models may register modifiers on this pipeline to contribute their own cause-specific rates.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

register_mortality_rate(builder)

Register the mortality rate attribute pipeline.

The attribute pipeline source is calculate_mortality_rate(), which computes the mortality rate from the all-cause rate and the registered cause-specific rates.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

load_unmodeled_csmr(builder)

Load and sum the cause-specific mortality rates for all unmodeled causes.

Iterates over causes listed in configuration.mortality.unmodeled_causes and accumulates their CSMRs from the artifact. Returns 0.0 if no unmodeled causes are configured.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

float | DataFrame

Returns:

The summed CSMR for all unmodeled causes as a pandas.DataFrame, or 0.0 if there are no unmodeled causes.

register_unmodeled_csmr(builder)

Register the unmodeled cause-specific mortality rate pipeline.

Creates a risk-affected attribute pipeline for the unmodeled CSMR pipeline so that modeled risks can apply modifiers to unmodeled causes.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

update_exit_times(index, previous_exit_time)

Update exit times for simulants who have died.

Return type:

Series

Parameters:

• index (Index)

• previous_exit_time (Series)

initialize_mortality(pop_data)

Initialize mortality-related columns for new simulants.

Parameters:

pop_data (SimulantData) – Metadata about the simulants being initialized.

Return type:

None

on_time_step(event)

Apply mortality to the living population at each time step.

Determines which simulants die based on the current mortality rate, then probabilistically assigns a cause of death and calculates years of life lost for the deceased simulants.

Parameters:

event (Event) – The event that triggered this method call.

Return type:

None

calculate_mortality_rate(index)

Compute the mortality rate for the given simulants.

The mortality rate is calculated as a cause-deleted mortality rate:

ACMR - modeled_CSMR - unmodeled_CSMR_raw + unmodeled_CSMR_modified

where unmodeled_CSMR_modified is the attribute calculated after any risk modifiers have been applied.

Parameters:

index (Index) – Index of the simulants for whom to compute the rate.

Return type:

DataFrame

Returns:

A pandas.DataFrame with a single column 'other_causes' containing the mortality rate for each simulant.