Risk Effect Models

This module contains tools for modeling the relationship between risk exposure models and disease models.

class vivarium_public_health.risks.effect.RiskEffect(risk, target)[source]

A component to model the effect of a risk factor on an affected entity’s target rate.

This component can source data either from builder.data or from parameters supplied in the configuration.

For a risk named ‘risk’ that affects ‘affected_risk’ and ‘affected_cause’, the configuration would look like:

configuration:
     risk_effect.risk_name_on_affected_target:
        exposure_parameters: 2
        incidence_rate: 10

Parameters:

risk (str)
target (str)

EXPOSURE_CLASS: alias of Risk

property name: str: The name of this risk effect component.

class vivarium_public_health.risks.effect.NonLogLinearRiskEffect(risk, target)[source]

A component to model the exposure-parametrized effect of a risk factor.

More specifically, this models the effect of the risk factor on the target rate of some affected entity.

This component:

Reads TMRED data from the artifact and defines the TMREL.
Calculates the relative risk at TMREL by linearly interpolating over relative risk data defined in the configuration.
Divides relative risk data from configuration by RR at TMREL and clips to be greater than 1.
Builds a LookupTable that returns the exposure and RR of the left and right edges of the RR bin containing a simulant’s exposure.
Uses this LookupTable to modify the target pipeline by linearly interpolating a simulant’s RR value and multiplying it by the intended target rate.

Parameters:

risk (str)
target (str)

property configuration_defaults: dict[str, Any]

Default configuration values for this component.

Configuration structure:

{risk_effect_name}:
    data_sources:
        relative_risk:
            Source for relative risk data. Default is the artifact
            key ``{risk}.relative_risk``. The data must be a
            DataFrame with a numeric ``parameter`` column containing
            exposure thresholds and a ``value`` column with the
            corresponding relative risks.
        population_attributable_fraction:
            Source for PAF data. Default is the artifact key
            ``{risk}.population_attributable_fraction``. Used to
            adjust the target rate to account for the portion
            attributable to this risk.

property name: str: The name of this non-log-linear risk effect component.

build_rr_lookup_table(builder)[source]

Build a lookup table mapping exposure intervals to relative risks.

Define left and right edges of exposure bins and their corresponding relative risk values for piecewise linear interpolation.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: LookupTable
Returns:: A lookup table with columns for left/right exposure and left/right relative risk values.

load_relative_risk(builder, configuration=None)[source]

Load relative risk data, normalizing by RR at the TMREL.

Compute the Theoretical Minimum-Risk Exposure Level (TMREL) from TMRED data, interpolate RR at the TMREL, divide all RR values by this quantity, and clip to be at least 1.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.
configuration (LayeredConfigTree | None) – Optional configuration override. If None, use self.configuration.

Return type:

str | float | DataFrame

Returns:

The normalized relative risk data as a DataFrame.

Raises:

MissingDataError – If the TMRED data uses draw-level TMRELs or is not found.
ValueError – If the relative risk data fails validation (e.g. it is empty, or its parameter column is non-numeric or not monotonically increasing). See validate_rr_data().

get_relative_risk_source(builder)[source]

Build a callable that interpolates relative risk from exposure.

Use piecewise linear interpolation within the exposure bins defined by the relative risk lookup table.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: Callable[[Index], Series]
Returns:: A callable that accepts a simulant index and returns interpolated relative risk values.

validate_rr_data(rr_data)[source]

Validate the relative risk data for non-log-linear effects.

Verify that the parameter column contains numeric data and that values are monotonically increasing within each demographic group.

Parameters:: rr_data (DataFrame) – The relative risk data to validate.
Raises:: ValueError – If the relative risk data is empty, or if the parameter column is not numeric or is not monotonically increasing within demographic groups.
Return type:: None