# HCD APR Table A2 — archived snapshot & analysis (2026-08-01)

Frozen source data and code behind the CSA scoreboard hero and footnote
statistics. The live dataset updates weekly; all published figures refer to
this snapshot.

## Data

- `tablea2.csv.gz` — gzipped snapshot of HCD APR Table A2, downloaded
  2026-08-01 from:
  https://data.ca.gov/dataset/81b0841f-2802-403e-b48e-2ef4b751f77c/resource/fe505d9b-8c36-42ba-ba30-08bc4f34e022/download/tablea2.csv
  - sha256 of the **uncompressed** CSV:
    `07fc0ff79d83f076e45b50957c9d9b97b694d2a2f8e0a822ef2af0c3fa0243ca`
  - 920,915 rows, 69 columns, ~292 MB uncompressed.
- `tablea2_data_dictionary.docx` — HCD's official data dictionary for
  Table A2 (from the same data.ca.gov dataset page). Confirms that
  acutely-low (0–15% AMI) and extremely-low (15–30% AMI) are separate,
  additive income bands, not subsets of very-low (30–50%).

## Code (run against the uncompressed CSV in the parent folder)

- `scoreboard_footnote_numbers.py` — reproduces every figure published in
  the scoreboard hero + footnote (5.00-to-1 ratio, 422,087 / 84,382,
  moderate split, 93.7% rentals, "fewer than 1 in 380" ownership stat).
  Its verified output: `footnote_numbers_output.txt`.
- `apr_ownership_affordability.py` — full ownership × affordability
  analysis at building-permit stage (statewide + high-growth counties,
  strict/broad × with/without ADUs, by year). Output: `run_final2.txt`,
  `apr_ownership_affordability_summary.csv`.
- `rigor_checks.py` — pre-publication audit: dedup-key integrity and
  strategy sensitivity, tenure plausibility crosstab, numerator project
  audit, reverse-miscoding bound. Output: `rigor_output.txt`.

Reproduce with:

```bash
gunzip -k tablea2.csv.gz   # place tablea2.csv next to the scripts
python3 -m venv .venv && .venv/bin/pip install pandas
.venv/bin/python scoreboard_footnote_numbers.py
```

## Key methodology decisions

1. **Dedup:** jurisdictions re-report unfinished projects in successive
   annual filings, inflating naive sums ~18% at permit stage and ~10% at
   completion stage. We collapse to the earliest APR year per
   (jurisdiction, tracking ID, APN, issue date, unit category) and
   attribute each record to its actual issue-date year. The headline
   ratio is robust to this choice (5.0 deduped vs 5.2 raw).
2. **Income bands:** "very-low and low" sums four columns — acutely-low +
   extremely-low + very-low + low — per the data dictionary. The
   affordable count includes non-deed-restricted units (the reading most
   generous to the state).
3. **Ownership stat:** owner-tenure rows, deed-restricted VLI/LI columns
   only, ADUs excluded. Published as "fewer than 1 in 380" because a
   project-level audit found the computed numerator (1,306 units → 1 in
   388) is inflated by rental projects miscoded as Owner in the state
   data — verified examples: Arroyo Crossing II (Indio, LIHTC rental,
   CTCAC CA-21-656), Villa de Vida (Poway, Mercy Housing rental), Larkin
   Place (Claremont, supportive rental), Las Haciendas (Temecula,
   rental). The miscoding bias is one-directional: correcting it makes
   the ownership share rarer, so the published figure is a conservative
   floor.

- `scoreboard_pipeline_numbers.py` — deduped entitled/permitted/built rows
  for the /scoreboard pipeline table, 2021–2025, with tenure splits and the
  per-stage ownership stat. Output: `pipeline_numbers_output.txt`.
