Repository navigation
Document input variables: 613 of 925 inputs have no documentation, including the most-used household inputs #10275
Description
Problem
Most input variables have no documentation, so apps that let users describe a household cannot say what an input means or what to enter.
In policyengine-us 2.2.1 (from /us/metadata):
- 613 of 925 visible input variables have no
documentation. - 211 of 372 inputs under
household.*have none.
Many of them are the inputs users fill in most often. Of the 21 inputs that the PolicyEngine app features in its household builder, only 4 are documented (unemployment_compensation, taxable_private_pension_income, child_support_received, health_insurance_premiums). These have none:
| Variable | Module |
|---|---|
pre_subsidy_rent |
household.expense.housing |
mortgage_payments |
household.expense.housing |
homeowners_insurance |
household.expense.housing |
spm_unit_pre_subsidy_childcare_expenses |
household.expense.childcare |
pre_subsidy_electricity_expense |
household.expense.utilities |
gas_expense |
household.expense.utilities |
water_expense |
household.expense.utilities |
other_medical_expenses |
household.expense.health |
student_loan_interest |
household.expense.person |
spm_unit_assets |
household.assets |
household_vehicles_owned |
household.demographic.household |
tip_income |
household.income.person |
taxable_interest_income |
household.income.person.interest |
qualified_dividend_income |
household.income.person.dividends |
self_employment_income_before_lsr |
input |
social_security_retirement |
gov.ssa.ss |
social_security_disability |
gov.ssa.ss |
Some labels are also raw names, for example spm_unit_pre_subsidy_childcare_expenses → "SPM unit pre subsidy child care expenses" and qualified_dividend_income → "qualified dividend income" (lower case).
Request
- Add a one-sentence
documentationto each variable above: what the amount covers, whose it is (person, tax unit, SPM unit), and that it is annual where the period is a year. Example:pre_subsidy_electricity_expense— "What the SPM unit pays for electricity in a year, before any utility assistance." - Then work through the other undocumented
household.*inputs, most-used first. - Optionally, a test that fails when a new non-hidden input variable has no
documentation, so the gap does not grow back.
Context
The app now carries its own descriptions for these 17 inputs as a stopgap (PolicyEngine/policyengine-app-v2#1319). Once the model documents them, the app uses the model's text, because the model's documentation takes precedence there.
Activity