“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) –

CONFIGURATION_DEFAULTS: Dict[str, Any] = {'risk_attributable_disease': {'mortality': True, 'recoverable': True, 'threshold': None}}

A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations.

property name

Returns 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.

Returns:

The unique name of the component.

Return type:

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]]

property state_names

property transition_names

setup(builder)

Defines custom actions this component needs to run during the setup lifecycle phase.

This method is intended to be overridden by subclasses to perform any necessary setup operations specific to the component. By default, it does nothing.

Parameters:

builder (Builder) – The builder object used to set up the component.

Return type:

None

adjust_state_and_transitions()

load_cause_specific_mortality_rate_data(builder)

load_excess_mortality_rate_data(builder)

get_exposure_filter(distribution, exposure_pipeline, threshold)

on_initialize_simulants(pop_data)

Method that vivarium will run during simulant initialization.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the simulant initialization phase.

Parameters:

pop_data (SimulantData) – The data associated with the simulants being initialized.

Return type:

None

on_time_step(event)

Method that vivarium will run during the time_step event.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the time_step event.

Parameters:

event (Event) – The event object associated with the time_step event.

Return type:

None

compute_disability_weight(index)

compute_excess_mortality_rate(index)

adjust_cause_specific_mortality_rate(index, rate)

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 –

with_condition(index)