CausalFactor Effect Models

This module contains tools for modeling the relationship between causal factor exposure models and the models they affect.

class vivarium_public_health.causal_factor.effect.CausalFactorEffect(causal_factor, target)[source]

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

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

For a causal factor named ‘causal_factor’ that affects ‘affected_target’, the configuration would look like:

configuration:
     causal_factor_effect.causal_factor_name_on_affected_target:
        exposure_parameters: 2
        incidence_rate: 10

Parameters:

causal_factor (str)
target (str)

EXPOSURE_CLASS: alias of CausalFactor

property name: str: The name of this causal factor effect component.

static get_name(causal_factor, target)[source]

Return the component name for a causal factor and target pair.

Return type:

str

Parameters:

causal_factor (EntityString)
target (TargetString)

property configuration_defaults: dict[str, Any]

Default configuration values for this component.

Configuration structure:

{causal_factor_effect_name}:
    data_sources:
        relative_risk:
            Source for relative risk data. Default is the artifact
            key ``{causal_factor}.relative_risk``. Can also be:
            - A scalar value (e.g., ``1.5``)
            - A scipy.stats distribution name (e.g., ``"uniform"``)
              with parameters in ``data_source_parameters``
        population_attributable_fraction:
            Source for PAF data. Default is the artifact key
            ``{causal_factor}.population_attributable_fraction``. Used to
            adjust the target measure to account for the portion
            attributable to this causal factor.
    data_source_parameters:
        relative_risk: dict
            Parameters for scipy.stats distributions when using
            a distribution name as the ``relative_risk`` source.
            For example, ``{"loc": 1.0, "scale": 0.5}`` for a
            uniform distribution.

property is_exposure_categorical: bool: Whether the exposure distribution is categorical.

setup(builder)[source]

Set up the causal factor effect component.

Load distribution type and PAF data, define relative risk source, build relative risk lookup tables, register relative risk pipeline, and register target and calibration constant modifiers.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

build_rr_lookup_table(builder)[source]

Build a lookup table for relative risk data.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: LookupTable
Returns:: A lookup table of relative risk values.

get_calibration_constant_data(builder)[source]

Load calibration constant (PAF) data for this effect.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: SupportsFloat | Timedelta | timedelta | Timestamp | datetime | DataFrame | list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | tuple[SupportsFloat | Timedelta | timedelta | Timestamp | datetime, ...] | Mapping[str, list[SupportsFloat | Timedelta | timedelta | Timestamp | datetime] | list[str]]
Returns:: The calibration constant data.

get_distribution_type(builder)[source]

Get the distribution type for the causal factor from the configuration.

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

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

Load relative risk data from the configuration.

Attempt to interpret the configured source as a scipy.stats distribution name; if that fails, load it as artifact data.

Parameters:

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

Return type:

str | float | DataFrame

Returns:

The relative risk data.

Raises:

ConfigurationError – If the distribution parameters are invalid.

get_filtered_data(builder, data_source)[source]

Load data and filter to the target entity and measure.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.
data_source (str | float | DataFrame) – The data source identifier, scalar, or DataFrame.

Return type:

float | DataFrame

Returns:

The filtered data.

process_categorical_data(builder, rr_data)[source]

Process relative risk data for categorical exposures.

For scalar RR data with a dichotomous distribution, construct a DataFrame with exposed/unexposed categories. Pivot the data to wide format for use in a lookup table.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.
rr_data (str | float | DataFrame) – The relative risk data.

Return type:

tuple[str | float | DataFrame, list[str]]

Returns:

A tuple of the pivoted RR data and the list of value column names.

Raises:

ValueError – If scalar RR data is provided with a non-dichotomous distribution.

rebin_relative_risk_data(builder, relative_risk_data)[source]

Rebin relative risk data.

When the polytomous risk is rebinned, matching relative risk needs to be rebinned. After rebinning, rr for both exposed and unexposed categories should be the weighted sum of relative risk of the component categories where weights are relative proportions of exposure of those categories. For example, if cat1, cat2, cat3 are exposed categories and cat4 is unexposed with exposure [0.1,0.2,0.3,0.4], for the matching rr = [rr1, rr2, rr3, 1], rebinned rr for the rebinned cat1 should be: (0.1 rr1 + 0.2 * rr2 + 0.3 rr3) / (0.1+0.2+0.3)

Return type:: DataFrame
Parameters:: relative_risk_data (DataFrame)

get_relative_risk_source(builder)[source]

Build a callable that computes relative risk from exposure.

For continuous exposures, use TMRED-based log-linear scaling. For categorical exposures, look up the RR for each simulant’s exposure category.

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 relative risk values.

register_relative_risk_pipeline(builder)[source]

Register the relative risk pipeline with the simulation.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

register_target_modifier(builder)[source]

Register the relative risk as a modifier on the target pipeline.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

register_calibration_constant_modifier(builder)[source]

Register the PAF data as a modifier on the calibration constant pipeline.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None