Encode HUD Fair Market Rents as a CSV-backed lookup (Phase 1)

changelog.d/hud-fmr-encoding.added.md

@@ -0,0 +1 @@
+Added the HUD Fair Market Rent CSV data store, a `hud_fair_market_rent` variable, and a `download_hud_fmr` helper script (Phase 1: county-level FY2025 with a placeholder seed row — full data refresh runs via the script with a free HUD API key).

policyengine_us/parameters/gov/hud/fmr/README.md

@@ -0,0 +1,48 @@
+# HUD Fair Market Rents (FMRs)
+
+## What
+
+`fair_market_rents.csv` holds HUD's published Fair Market Rents at the county
+level, indexed by `(state, county_fips, year, bedrooms)`. FMRs are the
+40th-percentile gross-rent estimates HUD uses to cap rents under the Housing
+Choice Voucher program, set Low-Income Housing Tax Credit rent limits, and
+size other federal housing subsidies (24 CFR Part 888).
+
+The model variable `hud_fair_market_rent` reads from this CSV.
+
+## Scope today (Phase 1)
+
+- **Year**: FY2025 only.
+- **Geography**: county-level FMR area only (no SAFMR ZIP-level resolution
+  yet — that lands in Phase 1B).
+- **Seed data**: a handful of placeholder rows (LA County) so the variable
+  and tests have something to bind to. Run `tools/download_hud_fmr.py` to
+  populate the full ~3,000-row county file from HUD's published data.
+
+## Schema
+
+| column | type | meaning |
+|---|---|---|
+| `state` | str | two-letter state abbreviation |
+| `county_fips` | str | 5-digit county FIPS code (zero-padded) |
+| `year` | int | HUD fiscal year |
+| `bedrooms` | int | 0 (efficiency) through 4 |
+| `value` | float | monthly FMR in current-year dollars |
+
+## Refresh
+
+```
+python -m policyengine_us.tools.download_hud_fmr --year 2025 --output \
+    policyengine_us/parameters/gov/hud/fmr/fair_market_rents.csv
+```
+
+The script reads `HUD_API_TOKEN` from the environment (register a free key
+at <https://www.huduser.gov/hudapi/>). Re-running with a different `--year`
+appends rather than overwriting.
+
+## Source
+
+- HUD User FY2025 FMR documentation: <https://www.huduser.gov/portal/datasets/fmr.html>
+- Federal Register notice: <https://www.federalregister.gov/documents/2024/08/14/2024-18002>
+- Regulatory citation: 24 CFR §888 (FMR rules), 24 CFR §982.503 (HCV payment
+  standards bound to 90-110 percent of FMR).

policyengine_us/parameters/gov/hud/fmr/__init__.py

@@ -0,0 +1,10 @@
+import pandas as pd
+from pathlib import Path
+
+FOLDER = Path(__file__).parent
+
+fair_market_rents = pd.read_csv(
+    FOLDER / "fair_market_rents.csv",
+    dtype={"county_fips": str},
+)
+fair_market_rents["county_fips"] = fair_market_rents["county_fips"].str.zfill(5)