Risk Attributable Disease

RiskAttributableDisease provides an alternative to the standard state-machine disease model. Rather than defining explicit states and transitions, it derives a simulant’s disease status directly from their exposure to an associated risk factor.

This is a special way to implement a disease model — instead of constructing states and transitions manually, RiskAttributableDisease is currently the only implementation for custom disease models that tie disease status directly to risk factor exposure.

This approach is used for diseases where the condition is defined by a risk threshold — for example, diabetes mellitus defined by fasting plasma glucose above 7 mmol/L, or protein-energy malnutrition defined by child wasting exposure categories. In these cases the population attributable fraction is effectively 1.

How It Differs from DiseaseModel

In a standard DiseaseModel, you explicitly create states and transitions, then compose them into a model. A RiskAttributableDisease handles this automatically:

Two states are auto-created: the disease state (e.g., protein_energy_malnutrition) and a susceptible state (e.g., susceptible_to_protein_energy_malnutrition).
Transitions are determined by whether the simulant’s current exposure crosses the configured threshold. One forward transition is always created; a recovery transition is added if recoverable is True.
No explicit state machine — the component reads the risk’s exposure pipeline directly and updates the simulant’s disease status on each time step.

Construction requires the full entity strings for cause and risk:

from vivarium_public_health.disease import RiskAttributableDisease

rad = RiskAttributableDisease(
    "cause.protein_energy_malnutrition",
    "risk_factor.child_wasting",
)

Threshold Configuration

The threshold setting defines which exposure values correspond to the with-condition state.

Categorical Risks

For categorical risk factors (dichotomous, ordered polytomous, or unordered polytomous distributions), provide a list of category names whose exposure indicates disease:

protein_energy_malnutrition:
    threshold: ["cat1", "cat2"]
    mortality: true
    recoverable: true

A simulant whose exposure is in cat1 or cat2 is considered to have protein-energy malnutrition.

Continuous Risks

For continuous risk factors, provide a string with a comparison operator (> or <) and a numeric value:

diabetes_mellitus:
    threshold: ">7"
    mortality: true
    recoverable: false

A simulant with fasting plasma glucose greater than 7 mmol/L is considered diabetic. The recoverable: false setting means that once diagnosed, a simulant does not lose the condition even if their exposure later drops below the threshold.

Mortality and Disability

RiskAttributableDisease uses the ExcessMortalityState mixin and provides the same mortality and disability pipelines as a standard DiseaseState:

Disability weight — loaded from the artifact at {cause}.disability_weight and applied only to simulants with the condition.
Excess mortality rate — loaded from the artifact at cause.{cause_name}.excess_mortality_rate and added to the mortality rate pipeline.
Cause-specific mortality rate — loaded from the artifact at cause.{cause_name}.cause_specific_mortality_rate and registered as a modifier on the cause_specific_mortality_rate pipeline.

Both EMR and CSMR can be disabled by setting mortality: false in the configuration, in which case they default to 0.

Recoverability

The recoverable configuration flag controls whether simulants can transition back to the susceptible state when their exposure falls outside the threshold:

recoverable: true — on each time step, simulants whose exposure no longer meets the threshold are moved back to the susceptible state.
recoverable: false — once a simulant acquires the condition, they remain in the with-condition state regardless of future exposure changes. This is appropriate for conditions like diabetes that do not resolve simply because the defining biomarker improves.