Household Rebalancing Module

This module adjusts the synthetic population to match observed household size distributions by geography. It duplicates or removes households to align current counts with control totals, maintaining population consistency while preserving demographic characteristics. The module tracks marital status before and after rebalancing operations and stores removed households/persons in separate tables.

Key features:

  • Matches household counts to control totals by geography and household size.

  • Duplicates households (and their members) when counts are below target.

  • Removes households (and their members) when counts exceed target.

  • Preserves demographic characteristics through exact duplication/removal.

  • Tracks marital status changes for validation purposes.

  • Stores removed records in rebalanced_households and rebalanced_persons tables.

Caveats:

  • Requires a control table with year, geography, household size, and target count columns.

  • The control table index must be ‘year’ and must have exactly 3 columns.

  • Sampling with replacement is used when duplicating more households than available.

  • Most errors are handled with assertions; users should ensure data consistency.

  • Geographic and household size columns must match between households and control tables.

Module function

Module configuration options: HHRebalancingModuleConfig

demos.models.rebalancing.household_rebalancing(households, persons, year, get_new_households, get_new_person_id, rebalanced_households, rebalanced_persons)[source]

Adjust household counts to match control totals by geography and household size.

This step compares current household counts with control totals and duplicates or removes households as needed. It maintains population consistency by also updating the persons table and stores removed records for tracking purposes.

Parameters:

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

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

  • year (int) – The current simulation year.

  • get_new_households (callable) – Function to generate new unique household IDs.

  • get_new_person_id (callable) – Function to generate new unique person IDs.

  • rebalanced_households (orca.Table) – Table for storing removed household records.

  • rebalanced_persons (orca.Table) – Table for storing removed person records.

Return type:

None

Notes

  • Modifies households and persons tables in place by adding/removing records.

  • Uses module configuration to determine control table and column mappings.

  • Tracks marital status before and after operations in marital_rebalanced table.

  • Skips processing if no control data exists for the current year.

  • Sampling with replacement occurs when duplicating more households than available.