Disease Observers

This module contains tools for observing disease incidence and prevalence in the simulation.

class vivarium_public_health.results.disease.DiseaseObserver(disease)[source]

Observes disease counts and person time for a cause.

By default, this observer computes aggregate disease state person time and counts of disease events 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.

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

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

Parameters:: disease (str)

disease: The name of the disease being observed.

previous_state_column_name: The name of the column that stores the previous state of the disease.

step_size: The time step size of the simulation.

disease_model: The disease model for the disease being observed.

entity_type: The type of entity being observed.

entity: The entity being observed.

transition_stratification_name: The stratification name for transitions between disease states.

setup(builder)[source]

Set up the observer.

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

get_configuration_name()[source]

Returns the name of a concrete observer for use in the configuration

Return type:: str

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, registeres two.

While it’s typical for all stratification registrations to be encapsulated in a single class (i.e. the :class:ResultsStratifier <vivarium_public_health.results.stratification.ResultsStratifier), this observer registers two additional stratifications. While they could be registered in the ResultsStratifier as well, they are specific to this observer and so they are registered here while we have easy access to the required names and categories.

register_disease_state_stratification(builder)[source]

Register the disease state stratification.

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

register_transition_stratification(builder)[source]

Register the transition stratification.

This stratification is used to track transitions between disease states. It appends ‘no_transition’ to the list of transition categories and also includes it as an exluded category.

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

Notes

It is important to include ‘no_transition’ in bith the list of transition categories as well as the list of excluded categories. This is because it must exist as a category for the transition mapping to work correctly, but then we don’t want to include it later during the actual stratification process.

register_person_time_observation(builder, pop_filter)[source]

Register a person time observation.

Return type:

None

Parameters:

builder (Builder)
pop_filter (str)

register_transition_count_observation(builder, pop_filter)[source]

Register a transition count observation.

Return type:

None

Parameters:

builder (Builder)
pop_filter (str)

map_transitions(df)[source]

Map previous and current disease states to transition string.

Parameters:: df (DataFrame) – The DataFrame containing the disease states.
Return type:: Series
Returns:: The transitions between disease states.

initialize_previous_state(pop_data)[source]

Initialize the previous state column to the current state

Return type:: None
Parameters:: pop_data (SimulantData)

on_time_step_prepare(event)[source]

Update the previous state column to the current state.

This enables tracking of transitions between states.

Return type:: None
Parameters:: event (Event)

aggregate_state_person_time(x)[source]

Aggregate person time for the time step.

Parameters:: x (DataFrame) – The DataFrame containing the population.
Return type:: float
Returns:: The aggregated person time.

format(measure, results)[source]

Rename the appropriate column to ‘sub_entity’.

The primary thing this method does is rename the appropriate column (either the transition stratification name of the disease name, depending on the measure) to ‘sub_entity’. We do this here instead of the ‘get_sub_entity_column’ method simply because we do not want the original column at all. If we keep it here and then return it as the sub-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_measure_column(measure, results)[source]

Get the ‘measure’ column values.

Return type:

Series

Parameters:

measure (str)
results (DataFrame)

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)