more docs

Author: yamilbknsu

configuration/demos_config.toml

@@ -13,7 +13,7 @@ modules = [
     "birth",
     "education",
     "household_rebalancing",
-    "update_income"
+    "income_adjustment"
 ]
 output_tables = [
     "persons",

demos/models/income_adjustment.py

@@ -6,16 +6,38 @@
 import time
 from logging_logic import log_execution_time
 
+STEP_NAME = "income_adjustment"
 
-@orca.step("update_income")
-def update_income(persons, households, income_rates, year):
+@orca.step(STEP_NAME)
+def income_adjustment(persons, households, income_rates, year):
     """
-    Updating income for persons and households
+    Update person-level earnings based on county-specific income growth rates.
 
-    Args:
-        persons (DataFrameWrapper): DataFrameWrapper of persons table
-        households (DataFrameWrapper): DataFrameWrapper of households table
-        year (int): simulation year
+    This step applies multiplicative adjustments to person earnings using annual
+    growth rates that vary by county. It maintains geographic variation in income
+    trajectories while updating the entire population simultaneously.
+
+    Parameters
+    ----------
+    persons : orca.Table
+        The persons table containing individual-level attributes including earnings.
+    households : orca.Table
+        The households table containing household-level attributes including county ID.
+    income_rates : orca.Table
+        Table with annual income growth rates by county.
+    year : int
+        The current simulation year.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    - Modifies `persons.earning` in place using multiplicative adjustment.
+    - Requires `income_rates` table with columns: year, lcm_county_id, rate.
+    - All persons in the same county receive the same proportional adjustment.
+    - Rate of 0.05 means 5% growth (earnings multiplied by 1.05).
     """
     start_time = time.time()
     # TODO: CountyID is not being updated by default

demos/models/rebalancing.py

@@ -107,7 +107,6 @@ def household_rebalancing(households, persons, year, get_new_households, get_new
     new_person_rows = new_person_rows.merge(hh_mapping, left_on="household_id", right_on="orig_hh")
     new_person_rows["household_id"] = new_person_rows["new_hh"]
     new_person_rows.drop(["orig_hh", "new_hh"], inplace=True, axis=1)
-    # new_person_rows.household_id = new_person_rows.household_id.map(dict(zip(to_duplicate_hh, new_hh_ids)))
     new_person_rows.index = get_new_person_id(len(new_person_rows))
     households.local.loc[new_hh_ids] = new_hh_rows
     persons.local = pd.concat([persons.local, new_person_rows])

docs/source/api/income_module.rst

@@ -0,0 +1,29 @@
+Income Adjustment Module
+============================
+
+This module updates person-level earnings based on county-specific income growth rates.
+It applies annual adjustment factors to maintain realistic income trajectories over time,
+accounting for geographic variation in economic conditions. The module reads rate data
+from an external table and applies multiplicative adjustments to current earnings.
+
+Key features:
+
+- Applies county-specific income growth rates to person earnings.
+- Updates earnings multiplicatively based on annual rate data.
+- Maintains geographic variation in income growth patterns.
+- Simple, direct adjustment without complex modeling.
+
+Caveats:
+
+- Requires an `income_rates` table with columns: year, lcm_county_id, rate.
+- Assumes households table has `lcm_county_id` column for geographic mapping.
+- All persons in the same county receive the same proportional adjustment.
+- No validation of rate values; extreme rates could produce unrealistic results.
+- Designed for use as-is; users should ensure rate data is reasonable and complete.
+
+Module function
+---------------
+
+This module does not have configuration options
+
+.. autofunction:: demos.models.income_adjustment.income_adjustment

docs/source/api/modules.rst

@@ -11,4 +11,6 @@ DEMOS Modules
    kids_move_module
    mortality_module
    birth_module
-   education_module
+   education_module
+   rebalancing_module
+   income_module

docs/source/pages/intro.md

@@ -116,13 +116,13 @@ The `modules` parameter accepts a list of strings identifying the modules. By de
 ```
 modules = [
     "aging",
-    "education_model",
+    "education",
 ]
 ```
 
 ### Configuration of calibration procedures:
 
-Certain modules support calibration of the simulation to observed values. Specific calibration parameters can be set for each module that supports it. If no configuration is provided, calibration is not performed. Additionally, some modules (namely `employment` and `household_reorganization`) implement simultaneous calibration. While the `employment` module implements both types of calibration, only one of the two can be used. An error will be raised if two types of calibration are defined.
+Certain modules support calibration of the simulation output to observed values. Specific calibration parameters can be set for each module that supports it. If no configuration is provided, calibration is not performed. Additionally, some modules (namely `employment` and `household_reorganization`) implement simultaneous calibration. While the `employment` module implements both types of calibration, only one of the two can be used. An error will be raised if two types of calibration are defined.
 
 Calibration configuration is defined at `module-level-config.calibration_procedure` (`module-level-config` is defined differently for every module. The options are displayed [here](../api/configuration_module.rst) and in each module's documentation). We will use the `employment` module as an example.