Risk Observers

This module contains tools for observing risk exposure during the simulation.

class vivarium_public_health.results.causal_factor.CategoricalCausalFactorObserver(causal_factor)[source]

An observer for a categorical causal factor.

Observes category person time for a causal factor.

By default, this observer computes aggregate categorical person time 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:
        causal_factor_name:
            exclude:
                - "sex"
            include:
                - "sample_stratification"

Parameters:: causal_factor (str)

causal_factor: The name of the causal factor.

exposure_pipeline: The name of the pipeline that produces the causal factor exposure.

step_size: The time step size of the simulation.

categories: The categories of the causal factor.

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 a stratification and observation.

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

Notes

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 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 and value names.

aggregate_category_person_time(x)[source]

Aggregate the person time for this time step.

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

format(measure, results)[source]

Rename the appropriate column to ‘sub_entity’.

The primary thing this method does is rename the causal factor column to ‘sub_entity’. We do this here instead of the ‘get_sub_entity_column’ method simply because we do not want the causal factor 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)

class vivarium_public_health.results.causal_factor.CategoricalRiskObserver(risk)[source]

An observer for a categorical risk factor.

Observes category person time for a risk factor. This is a convenience subclass of CategoricalCausalFactorObserver for use with risk factors.

By default, this observer computes aggregate categorical person time 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:
        risk_name:
            exclude:
                - "sex"
            include:
                - "sample_stratification"

Parameters:: risk (str)

causal_factor: The name of the risk factor.

exposure_pipeline: The name of the pipeline that produces the risk factor exposure.

step_size: The time step size of the simulation.

categories: The categories of the risk factor.

property name: str

The name of the component.

By convention, these are in snake case with arguments of the __init__() appended and separated by ..

Names must be unique within a simulation.

The name is created by first converting the name of the class to snake case. Then, the names of the initialization parameters are appended, separated by .. If a parameter is an instance of Component, its name property is used; otherwise, the string representation of the parameter is used. The resulting string is stored in the _name attribute and returned.

IMPORTANT: this property must not be accessed within the __init__() functions of this component or its subclasses or its value may not be initialized correctly.

class vivarium_public_health.results.causal_factor.CategoricalInterventionObserver(intervention)[source]

An observer for a categorical intervention.

Observes category person time for an intervention. This is a convenience subclass of CategoricalCausalFactorObserver for use with interventions.

By default, this observer computes aggregate categorical person time 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:
        intervention_name:
            exclude:
                - "sex"
            include:
                - "sample_stratification"

Parameters:: intervention (str)

causal_factor: The name of the intervention.

exposure_pipeline: The name of the pipeline that produces the intervention exposure.

step_size: The time step size of the simulation.

categories: The categories of the intervention.

property name: str

The name of the component.

By convention, these are in snake case with arguments of the __init__() appended and separated by ..

Names must be unique within a simulation.

The name is created by first converting the name of the class to snake case. Then, the names of the initialization parameters are appended, separated by .. If a parameter is an instance of Component, its name property is used; otherwise, the string representation of the parameter is used. The resulting string is stored in the _name attribute and returned.

IMPORTANT: this property must not be accessed within the __init__() functions of this component or its subclasses or its value may not be initialized correctly.