More docs

Author: yamilbknsu

.github/workflows/black.yml

@@ -0,0 +1,23 @@
+name: Code style (Black)
+
+on:
+  push:
+    paths: ["**/*.py", "pyproject.toml"]
+  pull_request:
+
+jobs:
+  black:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install Black
+        run: |
+          python -m pip install --upgrade pip
+          pip install black==24.8.0
+      - name: Check formatting
+        run: black --check --diff .

configuration/demos_config.toml

@@ -4,30 +4,27 @@ base_year = 2010
 forecast_year = 2019
 calibrated_models_dir = "../data/calibrated_configs/custom/06197001"
 inconsistent_persons_table_behavior = "fix"
+modules = [
+    "aging",
+    "employment",
+    "household_reorg",
+    "kids_moving",
+    "fatality",
+    "birth",
+    "education",
+    "household_rebalancing",
+    "update_income"
+]
 output_tables = [
     "persons",
     "households",
-    "graveyard",
-    "run_times",
-    "marital_rebalanced",
-    "marital_status_output"
+    "run_times"
 ]
 initialize_empty_tables = [
     "graveyard",
     "rebalanced_persons",
     "rebalanced_households"
 ]
-modules = [
-    "aging",
-    "employment",
-    "household_reorg",
-    "kids_moving",
-    "mortality_model",
-    "birth_model",
-    "education_model",
-    "household_rebalancing",
-    "update_income"
-]
 
 # Data sources
 ## Synthetic population data
@@ -55,14 +52,14 @@ file_type = "csv"
 table_name = "income_rates"
 filepath = "../data/income_rates_06197001.csv"
 index_col = "year"
-custom_dtype_casting = {"lcm_county_id"= "object", "year"= "int", "rate"= "float"}
+custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "rate" = "float"}
 
 [[tables]]
 file_type = "csv"
 table_name = "hsize_ct"
 filepath = "../data/hsize_ct_06197001.csv"
 index_col = "year"
-custom_dtype_casting = {"lcm_county_id"="object", "year"="int", "hh_size"="object", "total_number_of_households"="int"}
+custom_dtype_casting = {"lcm_county_id" = "object", "year" = "int", "hh_size" = "object", "total_number_of_households" = "int"}
 
 ## Simultaneous Calibration data
 ### For simultaneous calibration, tables need 
@@ -81,25 +78,9 @@ index_col = "year"
 
 
 # Modules configuration
-
-## Employment
-# [employment_module_config.enter_model_calibration_procedure]
-# procedure_type = "rmse_error"
-# observed_values_table = "observed_entering_workforce"
-# tolerance_type = "relative"
-# tolerance = 0.01
-# max_iter = 1000
-
-# [employment_module_config.exit_model_calibration_procedure]
-# procedure_type = "rmse_error"
-# observed_values_table = "observed_exiting_workforce"
-# tolerance_type = "relative"
-# tolerance = 0.01
-# max_iter = 1000
-
 [employment_module_config.simultaneous_calibration_config]
 tolerance = 100
-max_iter = 2 # 100
+max_iter = 2
 learning_rate = 2
 momentum_weight = 0.3
 

demos/models/__init__.py

@@ -1,10 +1,10 @@
 from .data_fix import *
-from .aging import REQUIRED_COLUMNS as AGING_COLUMNS
+from .aging import *
 from .employment import *
 from .household_reorg import *
 from .marriage import *
 from .kids_moving import *
-from .mortality import *
+from .fatality import *
 from .birth import *
 from .education import *
 from .rebalancing import *

demos/models/birth.py

@@ -7,9 +7,25 @@
 from logging_logic import log_execution_time
 from config import DEMOSConfig, get_config
 
+STEP_NAME = "birth"
+REQUIRED_COLUMNS = []
+
 
 @orca.injectable(autocall=False)
 def get_new_person_id(n):
+    """
+    Generate new unique person IDs for newborns.
+
+    Parameters
+    ----------
+    n : int
+        Number of new person IDs to generate.
+
+    Returns
+    -------
+    np.ndarray
+        Array of new unique person IDs.
+    """
     persons = orca.get_table("persons")
     graveyard = orca.get_table("graveyard")
     rebalanced_persons = orca.get_table("rebalanced_persons")
@@ -28,21 +44,33 @@ def get_new_person_id(n):
     )
 
 
-@orca.step("birth_model")
-def birth_model(persons, households, observed_births_data, get_new_person_id, year):
+@orca.step(STEP_NAME)
+def birth(persons, households, get_new_person_id):
     """
-    Function to run the birth model at the household level.
-    The function updates the persons table.
-
-    Modifies State Variables:
-        - (Adds rows to `persons` table)
-
-    Args:
-        persons (DataFrameWrapper): DataFrameWrapper of the persons table
-        households (DataFrameWrapper): DataFrameWrapper of the households table
-
-    Returns:
-        None
+    Simulate household-level births and add new persons to the population.
+
+    This step applies the birth model to eligible households, determines which have a birth event,
+    and adds new babies to the persons table with default and inferred attributes.
+
+    Parameters
+    ----------
+    persons : orca.Table
+        The persons table containing individual-level attributes.
+    households : orca.Table
+        The households table containing household-level attributes.
+    get_new_person_id : callable
+        Function to generate new unique person IDs as needed.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    - Adds new rows to the persons table for each birth event.
+    - Babies are assigned default values for most attributes.
+    - Race is assigned based on household head if all members share the same race; otherwise, "other".
+    - Some attributes may be duplicated or missing if not set in input data.
     """
     start_time = time.time()
     birth_list = run_and_calibrate_birth_model(persons, households)

demos/models/education.py

@@ -6,23 +6,44 @@
 from logging_logic import log_execution_time
 from templates.utils.models import columns_in_formula
 
-
-@orca.step("education_model")
-def education_model(
+STEP_NAME = "education"
+REQUIRED_COLUMNS = [
+    "persons.edu",
+    "persons.student",
+]
+
+@orca.step(STEP_NAME)
+def education(
     persons, edu_highschool_proportion, edu_highschool_grads_proportion, year
 ):
     """
-    Run the education model and update the persons table
-
-    Modifies State Variables:
-        - persons.edu
-        - persons.student
-
-    Args:
-        persons (DataFrameWrapper): DataFrameWrapper of the persons table
-
-    Returns:
-        None
+    Simulate educational attainment and student status transitions.
+
+    This step applies the education model to eligible persons (age > 15 and currently students)
+    to determine who drops out. It advances students through grades and degrees, maintains
+    proportions of high school and GED graduates, and updates the persons table in place.
+
+    Parameters
+    ----------
+    persons : orca.Table
+        The persons table containing individual-level attributes.
+    edu_highschool_proportion : pandas.Series
+        Proportion of students in 11th and 12th grade.
+    edu_highschool_grads_proportion : pandas.Series
+        Proportion of students with GED or high school diploma.
+    year : int
+        The current simulation year.
+
+    Returns
+    -------
+    None
+
+    Notes
+    -----
+    - Modifies `persons.edu` and `persons.student` in place.
+    - Only persons older than 15 and currently students are considered for dropout modeling.
+    - Proportions for transitions (e.g., GED vs. diploma) are maintained using observed data.
+    - Some transitions use random assignment based on empirical proportions.
     """
     start_time = time.time()
 
@@ -88,16 +109,57 @@ def education_model(
 
 @orca.injectable(name="edu_highschool_proportion")
 def edu_highschool_proportion(data="persons.edu"):
+    """
+    Calculate the proportion of students in 11th and 12th grade.
+
+    Parameters
+    ----------
+    data : pandas.Series
+        The `edu` column from the persons table.
+
+    Returns
+    -------
+    pandas.Series
+        Proportion of students in 11th (15) and 12th (16) grade.
+    """
     return data[data.isin([15, 16])].value_counts(normalize=True)
 
 
 @orca.injectable(name="edu_highschool_grads_proportion")
 def edu_highschool_grads_proportion(data="persons.edu"):
+    """
+    Calculate the proportion of students with GED or high school diploma.
+
+    Parameters
+    ----------
+    data : pandas.Series
+        The `edu` column from the persons table.
+
+    Returns
+    -------
+    pandas.Series
+        Proportion of students with GED (16) or high school diploma (17).
+    """
     return data[data.isin([16, 17])].value_counts(normalize=True)
 
 
 @orca.column(table_name="persons")
 def education_group(data="persons.edu"):
+    """
+    Assign each person to an education group.
+
+    Categorizes persons into predefined education intervals for use in modeling and reporting.
+
+    Parameters
+    ----------
+    data : pandas.Series
+        The `edu` column from the persons table.
+
+    Returns
+    -------
+    pandas.Series
+        Categorical education group labels as strings.
+    """
     education_intervals = [0, 18, 22, 200]
     education_labels = ["lte17", "18-21", "gte22"]
     return pd.cut(

demos/models/mortality.py demos/models/fatality.pydemos/models/mortality.py renamed to demos/models/fatality.py

@@ -7,30 +7,46 @@
 from config import DEMOSConfig, get_config
 from templates.utils.models import columns_in_formula
 
-STEP_NAME = "mortality_model"
+STEP_NAME = "fatality"
 REQUIRED_COLUMNS = [
     "persons.MAR",
     "persons.relate",
 ]
 
 
 @orca.step(STEP_NAME)
-def mortality(persons, households, relational_adjustment_mapping, graveyard):
-    """Executes the `mortality` estimated model and updates the households and persons
-    table accordingly. Importantly, this module updates the `relate` column according to the
-    `relational_adjustment_mapping` table.
-
-    **Required tables:**
-        - persons
-        - households
-        - relational_adjustment_mapping
-
-    **Modifies State Variables:**
-        - persons.MAR
-        - persons.relate
-        - (Adds rows from `graveyard` table)
-        - (Removes rows from `persons` table)
-        - (Removes rows from `households` table)
+def fatality(persons, households, relational_adjustment_mapping, graveyard):
+    """
+    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.
+
+    Returns
+    -------
+    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.
     """
     start_time = time.time()