Household Reorganization Module

This module simulates household structure changes by executing three sub-models: marriage, divorce, and cohabitation. Each sub-model is controlled by an estimated logit model, and their outputs are used to update the persons and households tables in place.

Key features:

  • Runs marriage, divorce, and cohabitation models in a coordinated step.

  • Supports optional simultaneous calibration to fit model outputs to observed data.

  • Updates household and marital status for all persons, including moving individuals between households as needed.

  • Handles cohabitation transitions, marriage formation, and divorce events.

Notes

  • The outputs of the estimated models are as follows:

    • marriage_list: 0 = stay single, 1 = cohabitate, 2 = get married (opposite sex partner).

    • cohabitate_x_list: For cohabitating couples, indicates whether they break up (1), stay cohabitating (0), or get married (2).

    • divorce_list: For married couples, indicates whether they break up (1) or stay married (0).

  • Simultaneous calibration is optional and only runs if calibration data is provided in the configuration.

  • Most errors (e.g., inconsistent household structure) are handled silently; users should review logs for warnings.

  • Orca columns defined in this module are essential for correct logic and should not be overridden by users.

  • Caveats:

    • Households with multiple partners (relate == 1 or 13) are dropped silently.

    • Some logic (e.g., partner matching, household ID assignment) relies on random sampling and may not be fully reproducible unless a random seed is set.

    • The module assumes that all required columns are present in the persons and households tables.

    • If geoid_col is set in the config, county assignments are propagated to new households.

    • The logic for updating member_id after divorce is not fully documented and may need review.

    • The module does not enforce all possible invariants (e.g., every household has exactly one head) but attempts to fix common issues.

Module function

Module configuration options: HHReorgModuleConfig

demos.models.household_reorg.household_reorg(persons, households, year, get_new_households)[source]

Main step for household reorganization: executes marriage, divorce, and cohabitation sub-models.

This function runs all three estimated models, optionally calibrates them to observed data, and updates the persons and households tables in place. It handles the creation and dissolution of households, changes in marital status, and cohabitation transitions.

Parameters:

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

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

  • year (int) – The current simulation year.

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

Return type:

None

Notes

  • The outputs of the estimated models are used to update the simulation state in place.

  • Simultaneous calibration is performed if calibration data is provided in the configuration.

  • See module-level docstring for details on model outputs and caveats.

Orca Functions

demos.models.household_reorg.get_new_households(n)[source]

Generate new unique household IDs for use in household reorganization.

Ensures that new household IDs do not overlap with any existing or historical IDs in the persons, graveyard, or rebalanced_persons tables. Also expands the households table index as needed.

Parameters:

n (int) – Number of new household IDs to generate.

Returns:

Array of new unique household IDs.

Return type:

np.ndarray

Notes

  • This function is used internally by the household reorganization logic.

  • The method for adding empty rows to the households table may change in the future.

demos.models.household_reorg.persons_grouped_household(persons)[source]

Precompute a groupby object for persons by household_id.

Parameters:

persons (orca.Table) – The persons table.

Returns:

GroupBy object for persons grouped by household_id.

Return type:

pandas.core.groupby.DataFrameGroupBy

Notes

  • Used for efficient aggregation in household-level orca columns.

demos.models.household_reorg.cohabitate(persons)[source]

Binary column in persons table evaluating to True if person is cohabitating partner of household head or head in a household with a cohabitating partner

demos.models.household_reorg.is_not_married(persons)[source]

Binary column in persons table evaluating to True if a person is above 15 and is not married (MAR != 1). Used in interal logic.

demos.models.household_reorg.is_head(persons)[source]

Binary column in persons table evaluating to 1 if person is head of household

demos.models.household_reorg.race_head(persons)[source]

Combination of is_head and race_id

demos.models.household_reorg.age_head(persons)[source]

Evaluates to is_head * age

demos.models.household_reorg.hispanic_head(persons)[source]

Evaluates to is_head * hispanic

demos.models.household_reorg.gt2(persons_grouped_household)[source]

Binary column in households table evaluating to 1 if there are at least 2 people in the household

demos.models.household_reorg.hh_race_of_head(data='households.hh_race_id_of_head')[source]

Maps households.hh_race_id_of_head, which is a numeric value, into ‘white’, ‘black’, ‘asian’ or other

demos.models.household_reorg.hh_race_id_of_head(persons_grouped_household)[source]
demos.models.household_reorg.hh_size(persons_grouped_household)[source]
demos.models.household_reorg.simultaneous_calibration(sim_cal_config, persons, marriage_model, cohab_model, divorce_model, marriage_data, cohab_data, divorce_data)[source]

Perform simultaneous calibration of marriage, divorce, and cohabitation models.

Adjusts model parameters so that the combined outputs of the three estimated models (marriage, divorce, cohabitation) match observed aggregate statistics for married and divorced persons. Uses a simple gradient-based optimization with optional momentum.

Parameters:

  • sim_cal_config (SimultaneousCalibrationConfig) – Configuration for the calibration procedure (learning rate, tolerance, etc).

  • persons (orca.Table) – The persons table.

  • marriage_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • cohab_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • divorce_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • marriage_data (pandas.DataFrame) – Data for each model to make predictions on.

  • cohab_data (pandas.DataFrame) – Data for each model to make predictions on.

  • divorce_data (pandas.DataFrame) – Data for each model to make predictions on.

Return type:

None

Notes

  • Only runs if calibration data is provided in the configuration.

  • Updates model parameters in place.

  • See module-level docstring for caveats.

demos.models.household_reorg.run_models(marriage_model, cohab_model, divorce_model, marriage_data, cohab_data, divorce_data)[source]

Run all three estimated models and return their outputs.

Parameters:

  • marriage_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • cohab_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • divorce_model (EstimatedModel) – Fitted estimated model objects for each sub-model.

  • marriage_data (pandas.DataFrame) – Data for each model to make predictions on.

  • cohab_data (pandas.DataFrame) – Data for each model to make predictions on.

  • divorce_data (pandas.DataFrame) – Data for each model to make predictions on.

Returns:

(marriage_list, divorce_list, cohabitate_x_list): - marriage_list: pd.Series, 0 = stay single, 1 = cohabitate, 2 = get married - divorce_list: pd.Series, 0 = stay married, 1 = divorce - cohabitate_x_list: pd.Series, 0 = stay cohabitating, 1 = break up, 2 = get married

Return type:

tuple

demos.models.household_reorg.print_marital_count(persons_df)[source]

Print the number of people with each marital status (MAR=1 or MAR=3).

Parameters:

persons_df (pandas.DataFrame) – DataFrame of persons, must include ‘MAR’ column.

Return type:

None

demos.models.household_reorg.compute_expected_marital_status(persons_df, cohabitate_x_list, marriage_list, divorce_list)[source]

Compute the expected number of married and divorced persons after applying model outputs.

Parameters:

  • persons_df (pandas.DataFrame) – DataFrame of persons, must include ‘MAR’, ‘relate’, ‘person_sex’, and ‘household_id’.

  • cohabitate_x_list (pd.Series) – Output of the cohabitation model (see module docstring for values).

  • marriage_list (pd.Series) – Output of the marriage model (see module docstring for values).

  • divorce_list (pd.Series) – Output of the divorce model (see module docstring for values).

Returns:

(n_married_after, min_div, max_div): - n_married_after: int, expected number of married persons after updates - min_div: int, minimum expected number of divorced persons - max_div: int, maximum expected number of divorced persons

Return type:

tuple

Notes

  • Used for calibration and reporting.

  • Logic is based on current and predicted statuses.

demos.models.household_reorg.print_household_stats()[source]
demos.models.household_reorg.update_cohabitating_households(persons, households, cohabitate_list, get_new_households)[source]

Updating households and persons after cohabitation model.

Parameters:

  • persons (DataFrameWrapper) – DataFrameWrapper of persons table

  • households (DataFrameWrapper) – DataFrameWrapper of households table

  • cohabitate_list (pd.Series) – Pandas Series of cohabitation model output

Returns:

None

demos.models.household_reorg.fix_erroneous_households(persons)[source]