“Special” Disease Models

This module contains frequently used, but non-standard disease models.

class vivarium_public_health.disease.special_disease.RiskAttributableDisease(cause, risk)

Component to model a disease fully attributed by a risk.

For some (risk, cause) pairs with population attributable fraction equal to 1, the clinical definition of the with condition state corresponds to a particular exposure of a risk.

For example, a diagnosis of diabetes_mellitus occurs after repeated measurements of fasting plasma glucose above 7 mmol/L. Similarly, protein_energy_malnutrition corresponds to a weight for height ratio that is more than two standard deviations below the WHO guideline median weight for height. In the Global Burden of Disease, this corresponds to a categorical exposure to child_wasting in either cat1 or cat2.

The definition of the disease in terms of exposure should be provided in the threshold configuration flag. For risks with continuous exposure models, the threshold should be provided as a single float or int with a proper sign between “>” and “<”, implying that disease is defined by the exposure level “>” than threshold level or, “<” than threshold level, respectively.

For categorical risks, the threshold should be provided as a list of categories. This list contains the categories that indicate the simulant is experiencing the condition. For a dichotomous risk there will be 2 categories. By convention cat1 is used to indicate the with condition state and would be the single item in the threshold setting list.

In addition to the threshold level, you may configure whether there is any mortality associated with this disease with the mortality configuration flag.

Finally, you may specify whether an individual should “recover” from the disease if their exposure level falls outside the provided threshold.

In our provided examples, a person would no longer be experiencing protein_energy_malnutrition if their exposure drift out (or changes via an intervention) of the provided exposure categories. Having your fasting_plasma_glucose drop below a provided level does not necessarily mean you’re no longer diabetic.

To add this component, you need to initialize it with full cause name and full risk name, e.g.,

RiskAttributableDisease(‘cause.protein_energy_malnutrition’,

‘risk_factor.child_wasting’)

Configuration defaults should be given as, for the continuous risk factor,

diabetes_mellitus:

threshold : “>7” mortality : True recoverable : False

For the categorical risk factor,

protein_energy_malnutrition:

threshold : [‘cat1’, ‘cat2’] # provide the categories to get PEM. mortality : True recoverable : True

Parameters:

• cause (str)

• risk (str)

property name

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.

property configuration_defaults: dict[str, Any]

Provides default configuration values for this component.

Configuration structure:

{component_name}:
    data_sources:
        raw_disability_weight:
            Source for disability weight data. Default is the
            artifact key ``{cause}.disability_weight``.
        cause_specific_mortality_rate:
            Source for cause-specific mortality rate data. Default
            uses ``load_cause_specific_mortality_rate_data`` method
            which loads from artifact if ``mortality`` is True.
        excess_mortality_rate:
            Source for excess mortality rate data. Default uses
            ``load_excess_mortality_rate_data`` method which loads
            from artifact if ``mortality`` is True.
        population_attributable_fraction:
            Source for PAF data. Default is 0, indicating no
            mediated effects from other risks.
    threshold: str or list
        Exposure threshold defining disease state. For continuous
        risks, provide a string like ``">7"`` or ``"<5"``.
        For categorical risks, provide a list of categories
        (e.g., ``['cat1', 'cat2']``).
    mortality: bool
        Whether this disease has associated mortality. Default
        is True.
    recoverable: bool
        Whether simulants can recover from this disease when
        their exposure falls outside the threshold. Default
        is True.

property state_names: list[str]

List of names of all states in this disease model.

property transition_names: list[TransitionString]

List of names of all transitions in this disease model.

setup(builder)

Perform this component’s setup.

Parameters:

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

Return type:

None

adjust_state_and_transitions()

Add recovery transition if the disease is recoverable.

Return type:

None

load_cause_specific_mortality_rate_data(builder)

Load cause-specific mortality rate data.

Parameters:

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

Return type:

float | DataFrame

Returns:

The cause-specific mortality rate data, or 0 if mortality is disabled.

load_excess_mortality_rate_data(builder)

Load excess mortality rate data.

Parameters:

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

Return type:

float | DataFrame

Returns:

The excess mortality rate data, or 0 if mortality is disabled.

get_exposure_filter(distribution, threshold)

Build a filter function that identifies simulants with the condition.

Parameters:

• distribution (str) – The risk’s exposure distribution type.

• threshold (Any) – The exposure threshold defining the disease state. For continuous risks, a string like “>7”. For categorical risks, a list of category names.

Return type:

Callable

Returns:

A function that takes a simulant index and returns a boolean series indicating which simulants have the condition.

initialize_disease(pop_data)

Initialize disease state for new simulants based on exposure.

Parameters:

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

Return type:

None

on_time_step(event)

Update disease state based on current exposure levels.

Parameters:

event (Event) – The event that triggered this method call.

Return type:

None

compute_disability_weight(index)

Get the disability weight associated with this disease.

Parameters:

index – An iterable of integer labels for the simulants.

Returns:

An iterable of disability weights indexed by the provided index.

Return type:

pd.Series[float]

compute_excess_mortality_rate(index)

Get the excess mortality rate associated with this disease.

Parameters:

index – An iterable of integer labels for the simulants.

Returns:

An iterable of excess mortality rates indexed by the provided index.

Return type:

pd.Series[float]

adjust_cause_specific_mortality_rate(index, rate)

Modify the cause-specific mortality rate for the given simulants.

Parameters:

• index – An iterable of integer labels for the simulants.

• rate – The base cause-specific mortality rate.

Returns:

The adjusted cause-specific mortality rate.

Return type:

pd.Series[float]

adjust_mortality_rate(index, rates_df)

Modifies the baseline mortality rate for a simulant if they are in this state.

Parameters:

• index – An iterable of integer labels for the simulants.

• rates_df – A DataFrame of mortality rates.

Returns:

The modified DataFrame of mortality rates.

Return type:

pd.DataFrame

with_condition(index)

Get the subset of simulants who have this condition.

Parameters:

index – An iterable of integer labels for the simulants.

Returns:

The subset of simulants who are alive and have this condition.

Return type:

pd.Index[int]