The Disease Model

This module contains a state machine driver for disease models. Its primary function is to provide coordination across a set of disease states and transitions at simulation initialization and during transitions.

class vivarium_public_health.disease.model.DiseaseModel(cause, cause_type='cause', states=(), residual_state=None, cause_specific_mortality_rate=None)[source]

State machine model for disease progression.

This component manages a set of disease states and transitions between them. It handles initialization of simulant disease states based on prevalence data and tracks cause-specific mortality rates.

Parameters:

cause (str)
cause_type (str)
states (Iterable[BaseDiseaseState])
residual_state (BaseDiseaseState | None)
cause_specific_mortality_rate (DataInput | None)

property configuration_defaults: dict[str, Any]

Provides default configuration values for this disease model.

Configuration structure:

{disease_name}:
    data_sources:
        cause_specific_mortality_rate:
            Source for cause-specific mortality rate (CSMR) data.
            Default uses the ``load_cause_specific_mortality_rate``
            method which loads from artifact at
            ``cause.{cause_name}.cause_specific_mortality_rate``.

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)[source]

Perform this component’s setup.

Gathers initialization weights pipelines from states contained in the disease model and registers them to be run during population initialization.
Registers a modifier to adjust the cause-specific mortality rate based on the model’s states.

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

on_post_setup(event)[source]

Validate that all rate transitions use the same conversion type.

Parameters:: event (Event) – The event that triggered this method call.
Return type:: None

initialize_state(pop_data)[source]

Initialize the simulants in the population.

If all simulants are initialized at age 0, birth prevalence is used. Otherwise, prevalence is used.

Parameters:: pop_data (SimulantData) – Metadata about the simulants being initialized.
Return type:: None

load_cause_specific_mortality_rate(builder)[source]

Load cause-specific mortality rate data.

If no source was provided at construction, loads CSMR from the artifact. Returns 0.0 for causes that only have morbidity (YLD-only causes).

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: float | DataFrame
Returns:: The cause-specific mortality rate data.

adjust_cause_specific_mortality_rate(index, rate)[source]

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

Parameters:

index – The index of simulants for which to adjust the cause-specific mortality rate.
rate – The base cause-specific mortality rate.

Returns:

The adjusted cause-specific mortality rate.

Return type:

pd.Series[float]