Income Module

This module predicts household income using a regression model and optionally applies two post-prediction adjustments:

  1. Inflation adjustment – scales nominal income from the model’s estimation (reference) year to the current simulation year using annual CPI factors supplied by the user.

  2. Calibration – nudges the aggregate predicted income toward observed values using the same RMSE-based intercept-shift procedure used by the Mortality and Birth modules.

Key features:

  • Predicts log income via the income_nworkers regression model and exponentiates to recover level predictions.

  • Applies a cumulative inflation factor derived from a user-supplied table of annual adjustment rates when inflation_reference_year and inflation_adjustment_table are configured.

  • Optionally calibrates aggregate income to per-year observed targets.

Caveats:

  • Inflation adjustment requires all simulation years between inflation_reference_year and the forecast year to be present in the adjustment table; a KeyError is raised for missing years.

  • When inflation_reference_year equals the current simulation year no adjustment is applied.

  • If calibration is enabled it runs before inflation adjustment so that the calibration target values should also be expressed in reference-year nominal dollars (or consistently in the same price level as the model).

See also

Income Adjustment Module for the companion module that applies county-specific earnings growth rates to person-level wages each year.

Module configuration

class demos.config.IncomeModuleConfig(*args, **kwargs)[source]

Bases: BaseModel

Configuration for the Income module.

The income model predicts household income as nominal dollars for the year in which it was estimated (inflation_reference_year). When inflation_reference_year and inflation_adjustment_table are both provided, predictions are automatically scaled to the current simulation year using cumulative annual CPI adjustment factors read from that table.

Optionally, a calibration procedure can be configured to nudge aggregate income predictions toward observed values (same mechanics as the mortality and birth modules).

Inflation adjustment table format (index_col = "year"):

year,adjustment
2011,0.030
2012,0.021
...

The adjustment column must contain decimal annual inflation rates (e.g. 0.030 represents 3.0 %). The table must cover every year from inflation_reference_year (exclusive) through the last simulation year (inclusive). If the current simulation year equals inflation_reference_year, no adjustment is applied.

calibration_procedure: Optional[CalibrationConfig] = None

Optional calibration procedure to align aggregate predicted income with observed aggregate values. Uses the same RMSE-based mechanics as the mortality and birth calibration procedures. Omit (or comment out) this block to skip calibration.

inflation_adjustment_table: Optional[str] = None

Name of the orca table containing annual CPI inflation adjustment factors, or an inline DataSource definition (like a [[tables]] entry) that will be loaded automatically. The table must be indexed by year and include an adjustment column with decimal annual inflation rates. Must be set together with inflation_reference_year.

inflation_reference_year: Optional[int] = None

The reference year of the income model estimation. Predicted income values are expressed in nominal dollars for this year and will be scaled forward (or backward) to the current simulation year using the cumulative product of the annual adjustment factors. Must be set together with inflation_adjustment_table.

Module function

demos.models.income.income(households)[source]