Fatality Module

This module simulates mortality events in the synthetic population using an estimated model. It updates the persons and households tables to reflect deaths, reassigns household heads as needed, and ensures relational consistency using a mapping table. Deceased individuals are moved to a graveyard table.

Key features:

  • Applies a logit model to determine which persons die in the current year.

  • Removes deceased persons from the persons table and adds them to the graveyard.

  • Updates marital status: surviving spouses/partners become widowed.

  • Reassigns household heads if the current head dies, using partners or the oldest remaining member.

  • Updates the relate column for all household members using the relational adjustment mapping.

  • Cleans up households and persons to maintain simulation invariants.

Caveats:

  • The module assumes the presence of a relational_adjustment_mapping table to update relationships.

  • If a household head dies and no partner remains, the oldest person becomes the new head.

  • Some errors or inconsistencies (e.g., multiple spouses per household) are handled silently.

  • The logic for updating relationships may need to be revisited if the mapping table changes structure.

  • Designed for use as-is; users should not override orca columns or internal logic.

Module function

This module does not have configuration options

demos.models.fatality.fatality(persons, households, relational_adjustment_mapping, graveyard)[source]

Simulate mortality events and update the persons and households tables.

This step applies the mortality estimated model to determine which persons die in the current year. It removes deceased persons from the persons table, updates marital status and household relationships, and moves the deceased to the graveyard table. The relate column is updated using the relational adjustment mapping to ensure consistency.

Parameters:

  • persons (orca.Table) – The persons table containing individual-level attributes.

  • households (orca.Table) – The households table containing household-level attributes.

  • relational_adjustment_mapping (orca.Table) – Table mapping old relationship codes to new ones after a head of household dies.

  • graveyard (orca.Table) – Table for storing records of deceased individuals.

Return type:

None

Notes

  • Modifies persons.MAR, persons.relate, and removes rows from persons and households tables.

  • Adds rows to the graveyard table for deceased individuals.

  • Updates marital status: surviving spouses/partners become widowed.

  • If a household head dies, a partner or the oldest remaining member becomes the new head.

  • The relate column for all household members is updated using the mapping table.

  • Some errors (e.g., multiple spouses per household) are handled silently.