Exposure Model

This module contains tools for modeling categorical and continuous exposures.

class vivarium_public_health.causal_factor.exposure.CausalFactor(causal_factor)

A model for an attribute defined by either a continuous or a categorical value.

For example,

1. high systolic blood pressure as an attribute where the SBP is not dichotomized into hypotension and normal but is treated as the actual SBP measurement.

2. smoking as two categories: current smoker and non-smoker.

This component can source data either from builder.data or from parameters supplied in the configuration. If data is derived from the configuration, it must be an integer or float expressing the desired exposure level or a covariate name that is intended to be used as a proxy. For example, for a causal factor named “causal_factor”, the configuration could look like this:

configuration:
    causal_factor:
        exposure: 1.0

or

configuration:
    causal_factor:
        exposure: proxy_covariate

For polytomous causal factors, you can also provide an optional ‘rebinned_exposed’ block in the configuration to indicate that the causal factor should be rebinned into a dichotomous causal factor. That block should contain a list of the categories that should be rebinned into a single exposed category in the resulting dichotomous causal factor. For example, for a causal factor named “causal_factor” with categories cat1, cat2, cat3, and cat4 that you wished to rebin into a dichotomous causal factor with an exposed category containing cat1 and cat2 and an unexposed category containing cat3 and cat4, the configuration could look like this:

configuration:
    causal_factor:
       rebinned_exposed: ['cat1', 'cat2']

For alternative risk factors, you must provide a ‘category_thresholds’ block in the in configuration to dictate the thresholds that should be used to bin the continuous distributions. Note that this is mutually exclusive with providing ‘rebinned_exposed’ categories. For a causal factor named “causal_factor”, the configuration could look like:

configuration:
    causal_factor:
        category_thresholds: [7, 8, 9]

Parameters:

causal_factor (str)

exposure_distributions: dict[str, CausalFactorDistribution] = {'dichotomous': <class 'vivarium_public_health.causal_factor.distributions.DichotomousDistribution'>, 'ensemble': <class 'vivarium_public_health.causal_factor.distributions.EnsembleDistribution'>, 'lognormal': <class 'vivarium_public_health.causal_factor.distributions.ContinuousDistribution'>, 'normal': <class 'vivarium_public_health.causal_factor.distributions.ContinuousDistribution'>, 'ordered_polytomous': <class 'vivarium_public_health.causal_factor.distributions.PolytomousDistribution'>, 'unordered_polytomous': <class 'vivarium_public_health.causal_factor.distributions.PolytomousDistribution'>}

VALID_ENTITY_TYPES = []

property name: str

The name of this causal factor component.

property configuration_defaults: dict[str, Any]

Default configuration values for this causal factor component.

Configuration structure:

{causal_factor_name}:
    data_sources:
        exposure:
            Source for exposure data. Default is the artifact key
            ``{causal_factor}.exposure``.
        ensemble_distribution_weights:
            Source for ensemble distribution weights (only used
            for ensemble distributions). Default is the artifact
            key ``{causal_factor}.exposure_distribution_weights``.
        exposure_standard_deviation:
            Source for exposure standard deviation data (only used
            for continuous distributions). Default is the artifact
            key ``{causal_factor}.exposure_standard_deviation``.
    distribution_type: str
        Type of exposure distribution. Can be one of:
        ``"dichotomous"``, ``"ordered_polytomous"``,
        ``"unordered_polytomous"``, ``"normal"``, ``"lognormal"``,
        or ``"ensemble"``. Default loads from artifact at
        ``{causal_factor}.distribution``.
    rebinned_exposed: list[str]
        Categories to combine into a single "exposed" category
        when rebinning a polytomous causal factor to dichotomous. Only
        used with polytomous distributions. Default is empty
        list (no rebinning).
    category_thresholds: list[float]
        Thresholds for converting continuous distributions to
        categorical. Mutually exclusive with ``rebinned_exposed``.
        Default is empty list (no categorization).

setup(builder)

Set up the causal factor component.

Determine the distribution type, create the exposure distribution, obtain a randomness stream, register the exposure pipeline, and register a propensity initializer.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

get_distribution_type(builder)

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

If the configured distribution type is not one of the supported types, it is assumed to be a data source and the data is retrieved using the get_data method.

Parameters:

builder (Builder) – The builder object.

Return type:

str

Returns:

The distribution type.

get_exposure_distribution(builder)

Create and set up the exposure distribution component for the causal factor based on its distribution type.

Parameters:

builder (Builder) – The builder object.

Return type:

CausalFactorDistribution

Returns:

The exposure distribution.

Raises:

NotImplementedError – If the distribution type is not supported.

get_randomness_stream(builder)

Return a randomness stream for propensity initialization.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

RandomnessStream

Returns:

The randomness stream for this causal factor.

register_exposure_pipeline(builder)

Register the exposure pipeline with the simulation.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

initialize_propensity(pop_data)

Initialize propensity values for new simulants.

Parameters:

pop_data (SimulantData) – Metadata about the simulants being initialized.

Return type:

None