Mortality Observers

This module contains tools for observing cause-specific and excess mortality in the simulation, including “other causes”.

class vivarium_public_health.results.mortality.MortalityObserver[source]

Observe cause-specific deaths and YLLs (including “other causes”).

By default, this counts cause-specific deaths and years of life lost over the full course of the simulation. It can be configured to add or remove stratification groups to the default groups defined by a ResultsStratifier. The aggregate configuration key can be set to True to aggregate all deaths and YLLs into a single observation and remove the stratification by cause of death to improve runtime.

In the model specification, your configuration for this component should be specified as, e.g.:

configuration:
    stratification:
        mortality:
            exclude:
                - "sex"
            include:
                - "sample_stratification"

This observer needs to access the has_excess_mortality attribute of the causes we’re observing, but this attribute gets defined in the setup of the cause models. As a result, the model specification should list this observer after causes.

clock: The simulation clock.

causes_of_death: Causes of death to be observed.

property configuration_defaults: dict[str, Any]

Default configuration values for this observer.

Extends the base PublicHealthObserver configuration with mortality-specific settings.

Configuration structure:

stratification:
    {observer_name}:
        exclude: list[str]
            Stratification groups to exclude from results.
            Inherited from base observer.
        include: list[str]
            Additional stratification groups to include.
            Inherited from base observer.
        aggregate: bool
            If True, aggregates all deaths and YLLs into a
            single observation without cause-specific breakdown.
            Default is False (cause-specific results).

setup(builder)[source]

Set up the observer.

Return type:: None
Parameters:: builder (Builder)

set_causes_of_death(builder)[source]

Set the causes of death to be observed.

The causes to be observed are any registered components of class types found in the mortality_classes property.

Return type:: None
Parameters:: builder (Builder)

Notes

We do not actually exclude any categories in this method.

Also note that we add ‘not_dead’ and ‘other_causes’ categories here.

register_observations(builder)[source]

Register stratifications and observations.

Return type:: None
Parameters:: builder (Builder)

Notes

Ideally, each observer registers a single observation. This one, however, registers two.

While it’s typical for all stratification registrations to be encapsulated in a single class (i.e. the ResultsStratifier), this observer potentially registers an additional one. While it could be registered in the ResultsStratifier as well, it is specific to this observer and so it is registered here while we have easy access to the required categories.

count_deaths(x)[source]

Count the number of deaths that occurred during this time step.

Return type:: float
Parameters:: x (DataFrame)

calculate_ylls(x)[source]

Calculate the years of life lost during this time step.

Return type:: float
Parameters:: x (DataFrame)

format(measure, results)[source]

Rename the appropriate column to ‘entity’.

The primary thing this method does is rename the ‘cause_of_death’ column to ‘entity’ (or, it we are aggregating, and there is no ‘cause_of_death’ column, we simply create a new ‘entity’ column). We do this here instead of the ‘get_entity_column’ method simply because we do not want the ‘cause_of_death’ at all. If we keep it here and then return it as the entity column later, the final results would have both.

Parameters:

measure (str) – The measure.
results (DataFrame) – The results to format.

Return type:

DataFrame

Returns:

The formatted results.

get_entity_type_column(measure, results)[source]

Get the ‘entity_type’ column values.

Return type:

Series

Parameters:

measure (str)
results (DataFrame)

get_entity_column(measure, results)[source]

Get the ‘entity’ column values.

Return type:

Series

Parameters:

measure (str)
results (DataFrame)

get_sub_entity_column(measure, results)[source]

Get the ‘sub_entity’ column values.

Return type:

Series

Parameters:

measure (str)
results (DataFrame)