Delayed Effects

This module contains tools to represent delayed effects in a multi-state lifetable simulation.

class vivarium_public_health.mslt.delay.DelayedRisk(risk)[source]

A delayed risk represents an exposure whose impact takes time to come into effect (e.g., smoking uptake and cessation).

The data required by this component are:

Initial prevalence: The initial level of exposure and post-exposure.
Incidence rate: The rate at which people begin to be exposed. This should be specified separately for the BAU and the intervention scenario.
Remission rate: The rate at which people stop being exposed. This should be specified separately for the BAU and the intervention scenario.
Relative risk of mortality for currently exposed: (e.g., currently smoking); and
Relative risk of mortality for post-exposure: (e.g., stopped smoking \(0..N\) years ago).
Disease-specific relative risks for currently exposed: (e.g., currently smoking)
Disease-specific relative risks for post-exposure: (e.g., stopped smoking \(0..N\) years ago).

Note

The relative risks are defined in relation to the pre-exposure group (whose relative risks are therefore defined to be \(1\)).

The configuration options for this component are:

constant_prevalence (boolean, default is False): If this is set to True, the remission rate in both the BAU and intervention will be kept fixed at 0 (i.e., no remission).
tobacco_tax (boolean, default is False): If this is set to True, additional scaling effects are applied to both the incidence and remission rates.
delay (integer, default is 20): The number of years, after remission, during which relative risks decrease back to their baseline values.

Identify the disease(s) for which this delayed risk will have an effect in the simulation configuration. For example, to modify the incidence of CHD and stroke, this would look like:

components:
    mslt_port:
        population:
            - BasePopulation()
            - Mortality()
            - Disability()
        disease:
            - Disease('CHD')
            - Disease('Stroke')
        delay:
            - DelayedRisk('tobacco')
        ...
configuration:
    tobacco:
        constant_prevalence: False
        tobacco_tax: False
        delay: 20
        affects:
            # This is where the affected diseases should be listed.
            CHD:
            Stroke:

Parameters:: risk (str) –

property configuration_defaults: Dict[str, Any]

Provides a dictionary containing the defaults for any configurations managed by this component.

These default values will be stored at the component_configs layer of the simulation’s ConfigTree.

Returns:: A dictionary containing the defaults for any configurations managed by this component.
Return type:: Dict[str, Any]

property columns_created: List[str]

Provides names of columns created by the component.

Returns:: Names of the columns created by this component, or an empty list if none.
Return type:: List[str]

property columns_required: List[str] | None

Provides names of columns required by the component.

Returns:: Names of required columns not created by this component. An empty list means all available columns are needed. None means no additional columns are necessary.
Return type:: Optional[List[str]]

property initialization_requirements: Dict[str, List[str]]

Provides the names of all values required by this component during simulant initialization.

Returns:: A dictionary containing the additional requirements of this component during simulant initialization. An omitted key or an empty list for a key implies no requirements for that key during initialization.
Return type:: Dict[str, List[str]]

setup(builder)[source]

Configure the delayed risk component.

This involves loading the required data tables, registering event handlers and rate modifiers, and setting up the population view.

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

get_bin_names()[source]

Return the bin names for both the BAU and the intervention scenario.

These names take the following forms:

"name.no": The number of people who have never been exposed.
"name.yes": The number of people currently exposed.
"name.N": The number of people N years post-exposure.

The final bin is the number of people \(\ge N\) years post-exposure.

The intervention bin names take the form "name_intervention.X".

register_modifier(builder, disease)[source]

Register that a disease incidence rate will be modified by this delayed risk in the intervention scenario.

Parameters:

builder (Builder) – The builder object for the simulation, which provides access to event handlers and rate modifiers.
disease (str) – The name of the disease whose incidence rate will be modified.

Return type:

None

on_initialize_simulants(pop_data)[source]

Define the initial distribution of the population across the bins, in both the BAU and the intervention scenario.

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

on_time_step_prepare(event)[source]

Account for transitions between bins, and for mortality rates.

These transitions include: - New exposures - Cessation of exposure - Increased duration of time since exposure

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

incidence_adjustment(disease, index, incidence_rate)[source]

Modify a disease incidence rate in the intervention scenario.

Parameters:

disease (str) – The name of the disease.
index (Index) – The index into the population life table.
incidence_rate (Series) – The un-adjusted disease incidence rate.

Return type:

Series

vivarium_public_health.mslt.delay.pivot_load(builder, entity_key)[source]

Helper method for loading dataframe from artifact.

Performs a long to wide conversion if dataframe has an index column named ‘measure’.

Parameters:

builder (Builder) –
entity_key (str) –

Return type:

DataFrame