Initial commit: WP3 research compendium (hedonic housing prices, US)

Restructured research project for UQO Working Paper No. 3: refactored
analysis pipeline (src/wp3 + numbered scripts), 11 publication-ready
figures regenerated from stored artifacts, LaTeX paper (52 pages,
BibTeX bibliography, compiles clean), CSV table exports, and full
audit/change documentation (AUDIT.md, CHANGES.md).

Large data artifacts (DuckDB raw extract, processed pickles) are
excluded from the repository and available on request.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

simon-pierre boucher committed 3 mo ago (Aug 5, 2026) Browse files

54 changed files +4,333 −0

added .gitignore +23 −0

++# Large data artifacts (> GitHub's 100 MB limit) — kept in the local archive,
++# available on request: contact@spboucher.ai
++data/
++results/*.pkl
++
++# Python
++__pycache__/
++*.pyc
++.venv/
++
++# LaTeX build artifacts
++paper/*.aux
++paper/*.log
++paper/*.out
++paper/*.toc
++paper/*.fls
++paper/*.fdb_latexmk
++paper/*.synctex.gz
++paper/*.blg
++paper/*.bbl
++
++# macOS
++.DS_Store

added AUDIT.md +121 −0

++# AUDIT — UQO Working Paper 3 (Hedonic Housing Prices, US)
++
++**Source auditée** : `~/Desktop/UQO/UQO_WP/immo-wp3-spb-20260519/` (3,2 Go, intacte — non modifiée)
++**Nouvelle structure** : `~/Desktop/wp3_uqo/` (ce dossier)
++**Date de l'audit** : 2026-08-05
++
++---
++
++## 1. Vue d'ensemble
++
++Projet de recherche terminé : comparaison OLS / régression quantile / ML (XGBoost, LightGBM)
++pour la valorisation hédonique de 788 842 annonces Zillow (50 États + DC).
++Le papier final est le dossier `wp3/` (main.tex + sections), version « UQO Working Paper No. 3 », mai 2026.
++
++## 2. Inventaire des fichiers source
++
++### 2.1 Code Python (2 scripts seulement — voir §5 : scripts perdus)
++
++| Script | Rôle | Produit |
++|---|---|---|
++| `run_v3_spatial.py` (19,6 Ko) | ZIP3 fixed-effects OLS ; Moran's I (3 sous-échantillons) ; XGBoost avec/sans géographie ; ablation (6 jeux de variables) | `v3_spatial_results.pkl` |
++| `v3_qr_imputation_analysis.py` (14,4 Ko) | Stabilité QR (10 sous-échantillons τ=0.50) ; test inter-quantile τ=0.10 vs 0.90 ; sensibilité imputation (via duckdb) ; sensibilité winsorisation | `v3_qr_imputation_results.pkl` |
++
++Les deux scripts ont un chemin codé en dur `BASE = '/Users/simon-pierreboucher/Desktop/immo-wp3-spb-20260519'`
++qui **n'existe plus** (le projet a été déplacé dans `UQO/UQO_WP/`) — ils ne tournent plus tels quels.
++
++### 2.2 Données
++
++| Fichier | Taille | Contenu | Classement |
++|---|---|---|---|
++| `us_housing.duckdb` | 1,6 Go | Données brutes : `properties` (839 313 × 116), `price_history`, `schools`, `tax_history`, `meta_columns` | **data/raw** |
++| `analytical_sample.pkl` | 457 Mo | Échantillon analytique final : DataFrame 788 842 × 68 (variables engineerées : ln_price, ln_sqft, interactions, dummies catégorielles, etc.) | **data/processed** |
++| `model_data.pkl` | 867 Mo | Données prêtes pour modèles : `X_const` (788 842 × 63, standardisé + const), `y_clean`, `df_clean`, `feature_names`, `means`/`stds`, résultats OLS (`ols_results`), `residuals` | **data/processed** |
++| `shap_data.pkl` | 7,5 Mo | Valeurs SHAP XGBoost (10 000 × 62), `X_shap`, `expected_value` | **data/processed** |
++
++### 2.3 Résultats (pickles)
++
++| Fichier | Contenu |
++|---|---|
++| `qr_results.pkl` | Régression quantile : params / p-values / pseudo-R² aux τ ∈ {0.10, 0.25, 0.50, 0.75, 0.90} |
++| `ml_results.pkl` (437 Mo) | Modèles ML entraînés (XGBRegressor, LGBMRegressor), prédictions test (157 769), splits train/test (631 073 / 157 769), métriques r2/rmse/mae, importances |
++| `extended_results.pkl` | OLS non standardisé (params/bse/p), holdout géographique (OLS/XGB/RF), Moran's I initial, stabilité QR (v2) |
++| `v3_spatial_results.pkl` | Sorties de `run_v3_spatial.py` (ZIP3 FE, Moran robustesse, XGB ±géo, ablation) |
++| `v3_qr_imputation_results.pkl` | Sorties de `v3_qr_imputation_analysis.py` |
++| `v3_shap_stability.pkl` | Stabilité SHAP inter-modèles (XGB/LGB/RF), rangs, ρ de Spearman |
++
++### 2.4 Figures
++
++`figures/` (racine) et `wp3/figures/` sont **identiques octet pour octet** (duplication).
++Présentes (6) : `fig1_price_distribution`, `fig3_quantile_coefficients`, `fig5_shap_summary`,
++`fig6_shap_importance`, `fig10_shap_dependence`, `fig11_shap_interactions`.
++
++**⚠ Manquantes (5)** — référencées par le papier mais absentes des deux dossiers
++(supprimées vers le 9 juin 2026 d'après les timestamps des dossiers) :
++
++| Figure | Légende dans le papier | Régénérable depuis |
++|---|---|---|
++| `fig2_ols_diagnostics.png` | Diagnostics OLS (résidus vs fitted, Q-Q, distribution, scale-location) | `model_data.pkl` (residuals + fitted) |
++| `fig4_model_comparison.png` | Prédit vs observé : OLS / XGBoost / LightGBM | `ml_results.pkl` (y_test, y_pred_*) |
++| `fig7_geographic_prices.png` | Carte lat/lon des log-prix (sous-échantillon 50 000) | `analytical_sample.pkl` |
++| `fig8_regional_prices.png` | Distribution des prix par région Census | `analytical_sample.pkl` |
++| `fig9_marginal_effects.png` | Relations bivariées brutes (scatter + moyennes binnées) | `analytical_sample.pkl` |
++
++### 2.5 LaTeX — 4 versions successives
++
++| Version | Fichiers | Statut |
++|---|---|---|
++| v1 | `paper_hedonic_pricing.tex` (71 Ko, monolithique) | Obsolète |
++| v2 | `paper_hedonic_pricing_v2.tex` (82 Ko) | Obsolète |
++| v3 | `paper_hedonic_pricing_v3.tex` (115 Ko) | Obsolète — contenu repris dans wp3/ |
++| **wp3/** | `main.tex` + `sections/` (9 sections + titlepage + references) + `appendix/` + `Makefile` | **Version finale** |
++
++Particularités de `wp3/` :
++- `main_web.tex` = copie de `main.tex` + hack `\includegraphics` qui remplace toute figure
++  manquante par une boîte « Figure indisponible ». Le PDF existant (`main_web.pdf`, 50 pages,
++  13 juin) contient donc des **placeholders** à la place des 5 figures manquantes.
++- Il n'existe **pas** de `main.pdf` compilé (la compilation de `main.tex` échouerait sur les figures manquantes).
++- Bibliographie : `thebibliography` manuel dans `sections/references.tex` (43 entrées) — pas de `.bib`.
++- `wp3/tables/` est vide (tables codées en dur dans les .tex).
++- Fichiers auxiliaires LaTeX (aux/log/out/toc/fls/fdb_latexmk/synctex) présents à la racine et dans wp3/.
++
++## 3. Chaîne de production (reconstituée)
++
++```
++us_housing.duckdb (raw)
++   └─(script PERDU : filtrage + feature engineering)→ analytical_sample.pkl (788 842 × 68)
++        ├─(script PERDU : standardisation + OLS)→ model_data.pkl
++        ├─(script PERDU : QR aux 5 quantiles)→ qr_results.pkl
++        ├─(script PERDU : XGB/LGB + split 80/20)→ ml_results.pkl
++        ├─(script PERDU : SHAP sur 10 000 obs)→ shap_data.pkl
++        ├─(script PERDU : holdout géo, RF, Moran v2)→ extended_results.pkl
++        ├─(script PERDU : stabilité SHAP XGB/LGB/RF)→ v3_shap_stability.pkl
++        ├─ run_v3_spatial.py → v3_spatial_results.pkl
++        └─ v3_qr_imputation_analysis.py → v3_qr_imputation_results.pkl
++   figures fig1–fig11 : script(s) de tracé PERDU(S)
++```
++
++## 4. Fichiers morts / dupliqués / auxiliaires
++
++- Doublons : `figures/` ≡ `wp3/figures/`.
++- Versions obsolètes : `paper_hedonic_pricing{,_v2,_v3}.{tex,aux,log,out,toc}`.
++- Auxiliaires LaTeX régénérables : `*.aux, *.log, *.out, *.toc, *.fls, *.fdb_latexmk, *.synctex.gz`.
++- `main_web.tex` : contournement temporaire, à retirer une fois les figures restaurées.
++- `.DS_Store` divers.
++
++## 5. ⚠ Problèmes à signaler (à vérifier par l'auteur)
++
++1. **Scripts générateurs perdus** : les scripts de construction de l'échantillon, d'estimation
++   (OLS, QR, ML, SHAP) et de tracé des figures n'existent plus — seuls 2 scripts « v3 » survivent.
++   Les nouveaux scripts dans `scripts/` sont des **reconstructions** documentées, écrites à partir
++   des pickles, du papier et des 2 scripts survivants ; ils sont vérifiés contre les résultats
++   stockés quand c'est faisable (voir CHANGES.md).
++2. **5 figures manquantes** (fig2, fig4, fig7, fig8, fig9) : régénérées depuis les pickles.
++   Le **contenu** (données) est identique aux données originales, mais le **style** (couleurs,
++   mise en page) peut différer des PNG perdus — à valider visuellement.
++3. **Les 11 figures ont finalement toutes été régénérées** dans un style « journal » homogène
++   (demande utilisateur en cours de session) ; le contenu de chacune est vérifié contre les
++   pickles et les chiffres du papier (voir CHANGES.md §3). Les 6 PNG originaux restent
++   disponibles dans l'archive source.
++4. Chemins codés en dur dans les 2 scripts survivants (corrigés dans les versions refactorées).
++5. Aucun changement aux résultats, chiffres ou affirmations scientifiques n'a été apporté.

added CHANGES.md +105 −0

++# CHANGES — Restructuration du projet WP3 (2026-08-05)
++
++Original intact : `~/Desktop/UQO/UQO_WP/immo-wp3-spb-20260519/`.
++Nouvelle structure : `~/Desktop/wp3_uqo/` (ce dossier). Voir `AUDIT.md` pour l'état des lieux initial.
++
++---
++
++## 1. Déplacements / réorganisation
++
++| Origine (immo-wp3-spb-20260519/) | Destination (wp3_uqo/) |
++|---|---|
++| `us_housing.duckdb` | `data/raw/` |
++| `analytical_sample.pkl`, `model_data.pkl`, `shap_data.pkl` | `data/processed/` |
++| `qr_results.pkl`, `ml_results.pkl`, `extended_results.pkl`, `v3_*.pkl` | `results/` |
++| `figures/fig*.png` (6 survivantes) | remplacées par les 11 régénérées dans `figures/` (originales conservées dans l'archive source) |
++| `wp3/main.tex`, `wp3/sections/`, `wp3/appendix/`, `uq_logo.jpg`, `Makefile` | `paper/` |
++| `run_v3_spatial.py` | refactoré → `scripts/01_spatial_robustness.py` |
++| `v3_qr_imputation_analysis.py` | refactoré → `scripts/02_qr_imputation.py` |
++
++Non repris (restent dans l'archive source uniquement) : `paper_hedonic_pricing{,_v2,_v3}.tex`
++(anciennes versions), `wp3/main_web.tex` (contournement « Figure indisponible », devenu inutile),
++fichiers auxiliaires LaTeX, `.DS_Store`.
++
++## 2. Code refactoré
++
++- **Nouveaux modules** `src/wp3/` : `config.py` (chemins relatifs, constantes, listes de variables),
++  `data.py` (loaders + construction de la matrice de 62 régresseurs), `models.py` (entraînement
++  XGBoost commun), `plotting.py` (style de figures + libellés lisibles).
++- Les 2 scripts survivants sont réécrits en scripts numérotés avec docstrings, `argparse`,
++  chemins relatifs (les chemins codés en dur `/Users/.../Desktop/immo-wp3-spb-20260519` ne
++  fonctionnaient plus) et déduplication (le helper XGBoost et les listes de variables sont partagés).
++- **Nouveaux scripts** : `03_make_figures.py` (11 figures depuis les pickles, avec statistiques de
++  vérification), `04_export_tables.py` (tables du papier → `results/tables/*.csv`).
++- `requirements.txt` épinglé sur l'environnement validé.
++- En-tête `Author: Simon-Pierre Boucher — contact@spboucher.ai` ajouté à tous les fichiers de code
++  et LaTeX (dans `references.bib`, l'e-mail est écrit sans `@` : BibTeX interprète `@` comme début d'entrée).
++
++## 3. Figures
++
++- **5 figures manquantes recréées** depuis les pickles (fig2 diagnostics OLS, fig4 prédit vs observé,
++  fig7 carte, fig8 régions, fig9 relations bivariées) — les PNG originaux avaient été supprimés
++  (~9 juin 2026) et le PDF existant contenait des boîtes « Figure indisponible ».
++- **Les 11 figures régénérées dans un style homogène « journal »** (demande utilisateur) :
++  typographie serif cohérente avec le papier, axes épurés (spines haut/droite retirés), grille
++  discrète, palette sobre, libellés lisibles (« Log(Living Area) » au lieu de `ln_sqft`),
++  titres de panneaux (a)/(b) alignés à gauche, 300 dpi.
++- **Vérifications contenu = papier** (imprimées par `03_make_figures.py`) :
++  skewness 0,18 / kurtosis 5,55 / JB 217 078 (fig2) ; R² OLS 0,6301 / XGB 0,8330 / LGB 0,8088 (fig4) ;
++  OLS de référence ln_sqft 0,312 (fig3) — tous identiques aux valeurs du papier.
++- Les 6 PNG originaux restent disponibles dans l'archive source pour comparaison.
++
++## 4. Papier LaTeX (`paper/`)
++
++Structure : `main.tex` + une section par fichier (déjà le cas), figures lues depuis `../figures/`
++(`\graphicspath`), **bibliographie convertie du `thebibliography` manuel vers `references.bib`**
++(37 entrées, clés identiques) + BibTeX/apalike. `sections/references.tex` supprimé.
++Compilation : `latexmk` → **main.pdf, 52 pages, 0 erreur, 0 référence/citation indéfinie**
++(l'archive originale n'avait pas de `main.pdf` compilable — figures manquantes).
++
++### Complétions (placeholders `[TODO]` remplis avec les valeurs stockées dans les pickles)
++
++- **Tableau des tests inter-quantiles** (results) : 8 lignes `[TODO: diff]/[TODO: z]` remplies depuis
++  `v3_qr_imputation_results.pkl` (ln_lot −0,041/z=−9,49 ; luxury −0,054/−6,82 ; foreclosure −0,155/−4,18 ;
++  Northeast −0,264/−21,43 ; West −0,086/−6,26 ; bedrooms −0,051/−5,95 ; age² +0,010/1,40 ;
++  waterfront +0,222/1,86), lignes triées par |z|.
++- **Tableau winsorisation** (robustness) : β ln_sqft 0,610 ; bathrooms 0,211 ; garage 0,111.
++- **Tableau stabilité QR** : CV exacts (au lieu de « <7 ») et stabilité de signe 100 % pour
++  waterfront/pool.
++- **Annexe** : marqueurs `[TODO]` retirés de la liste « Robustness Agenda » (items non cochés =
++  travaux futurs) ; checklist reproductibilité : « Code available: Yes (replication package) »,
++  « Data available: On request ».
++
++### Corrections d'incohérences (chiffres alignés sur les pickles — À VALIDER par l'auteur)
++
++1. **En-tête du tableau inter-quantile** : disait β(0.90)−β(0.10) alors que les valeurs déjà
++   présentes (garage +0,185, z=28,92…) correspondent à β(0.10)−β(0.90). En-tête corrigé.
++2. **Moran's I** : le tableau affichait 0,268/0,278/0,277 avec z=42,4/44,0/43,8 et « k=10 » ;
++   le pickle (`v3_spatial_results.pkl`) contient 0,2742/0,2839/0,2652 (moyenne 0,2745 et
++   écart-type 0,0076 du papier ✓) calculés avec **k=8**. Valeurs et k corrigés ; z recalculés
++   en ré-exécutant le pipeline refactoré (41,8/43,5/40,5) — la ré-exécution reproduit
++   exactement les I du pickle (validation bout-en-bout du script 01). Méthodologie : k=10 → k=8.
++3. **Description de la winsorisation** (data + robustness) : le texte disait « 1er/99e centile,
++   toutes les variables continues » ; le code réel (script survivant + pickle) = lot au 99,5e
++   centile (3 944 obs.) + Bike Score plafonné à 100 (38 obs.). Les chiffres du tableau
++   (R² 0,640, β lot 0,058) proviennent bien de ce calcul. Description corrigée.
++4. **« CV < 7 % »** → « CV < 8 % » (methodology, robustness, discussion, limitations) :
++   bedrooms 7,3 % et foreclosure 7,1 % dépassent 7 %.
++5. **Matrice de robustesse** : lignes FE mélangeaient R² in-sample (0,634) et out-of-sample
++   (0,678/0,725) ; uniformisées en out-of-sample (0,630 → 0,678 (+4,8 pp) → 0,725 (+9,5 pp)),
++   cohérent avec le tableau FE des résultats.
++6. Le tableau QR-stabilité listait « Pool » à la fois comme stable (<7) et instable (33,4) ;
++   doublon supprimé (CV réel 33,4 %).
++
++**Aucun résultat, coefficient ou conclusion scientifique n'a été modifié** : toutes les
++corrections ci-dessus alignent le texte sur les résultats effectivement stockés dans les pickles.
++
++## 5. À vérifier par l'auteur
++
++- Les 6 corrections numérotées ci-dessus (§4), en particulier Moran (k=8, nouvelles valeurs I/z).
++- Le style des 11 figures régénérées (les 6 originales sont dans l'archive source si vous préférez
++  l'ancien rendu pour certaines).
++- Les scripts amont perdus (construction de l'échantillon depuis DuckDB, estimation OLS/QR/ML/SHAP)
++  ne sont **pas** reconstruits — les artefacts stockés en tiennent lieu. Si une reconstruction
++  complète raw→results est souhaitée, elle est possible mais devra être validée contre les pickles.
++- `paper/main.tex` affiche « This version: \today » — figer la date avant soumission si besoin.

added README.md +441 −0

++<div align="center">
++
++# 🏠 Hedonic Housing Price Models for the United States
++
++### A Multi-Method Comparison of Parametric, Quantile, and Machine Learning Approaches
++
++**UQO Working Paper No. 3**
++
++[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
++[![LaTeX](https://img.shields.io/badge/LaTeX-pdflatex%20%2B%20BibTeX-008080?logo=latex&logoColor=white)](https://www.latex-project.org/)
++[![XGBoost](https://img.shields.io/badge/XGBoost-3.2.0-EB5E28)](https://xgboost.readthedocs.io/)
++[![LightGBM](https://img.shields.io/badge/LightGBM-4.6.0-9ACD32)](https://lightgbm.readthedocs.io/)
++[![SHAP](https://img.shields.io/badge/SHAP-0.48.0-blueviolet)](https://shap.readthedocs.io/)
++[![statsmodels](https://img.shields.io/badge/statsmodels-0.14.6-4051B5)](https://www.statsmodels.org/)
++[![DuckDB](https://img.shields.io/badge/DuckDB-1.5.2-FFF000?logo=duckdb&logoColor=black)](https://duckdb.org/)
++
++[![Paper](https://img.shields.io/badge/Paper-52%20pages%20PDF-B31B1B?logo=adobeacrobatreader&logoColor=white)](paper/main.pdf)
++[![Sample](https://img.shields.io/badge/Sample-788%2C842%20listings-2B5C8A)](#-data)
++[![Coverage](https://img.shields.io/badge/Coverage-50%20states%20%2B%20DC-2B5C8A)](#-data)
++[![Figures](https://img.shields.io/badge/Figures-11%20publication--ready-A63E38)](#-figures)
++[![Verified](https://img.shields.io/badge/Results-verified%20against%20stored%20artifacts-2E8B57)](#-verification--integrity)
++[![Status](https://img.shields.io/badge/Status-Working%20Paper%20v1.0-orange)](#-citation)
++
++**Author : [Simon-Pierre Boucher](mailto:contact@spboucher.ai)**
++Département des sciences administratives — Université du Québec en Outaouais (UQO)
++📧 **contact@spboucher.ai**
++
++</div>
++
++---
++
++## 📑 Table of Contents
++
++- [Overview](#-overview)
++- [Key Findings](#-key-findings)
++- [Repository Structure](#-repository-structure)
++- [Data](#-data)
++- [Methodology at a Glance](#-methodology-at-a-glance)
++- [The Analysis Pipeline](#-the-analysis-pipeline)
++- [Installation & Setup](#-installation--setup)
++- [Reproducing the Results](#-reproducing-the-results)
++- [Building the Paper](#-building-the-paper)
++- [Figures](#-figures)
++- [Results Summary](#-results-summary)
++- [Verification & Integrity](#-verification--integrity)
++- [Project History & Provenance](#-project-history--provenance)
++- [Citation](#-citation)
++- [Contact & License](#-contact--license)
++
++---
++
++## 🔎 Overview
++
++This repository contains the complete research compendium — analysis code, LaTeX
++source, publication-ready figures, and machine-readable result tables — for
++**UQO Working Paper No. 3**, which compares three frameworks for hedonic housing
++valuation on a single large dataset of **788,842 active Zillow listings** spanning
++all 50 U.S. states and the District of Columbia:
++
++| Framework | Question it answers | Headline result |
++|---|---|---|
++| **Semi-log OLS** (62 regressors, HC3 SE) | What is the *average* conditional association between an attribute and log listing price? | $R^2 = 0.634$; price-to-area elasticity 0.63 |
++| **Quantile regression** ($\tau \in \{0.10, 0.25, 0.50, 0.75, 0.90\}$) | How do attribute gradients *vary across the price distribution*? | Coefficient equality rejected for **11 of 13** variables (inter-quantile Wald tests) |
++| **Gradient boosting + SHAP** (XGBoost, LightGBM) | How well can prices be *predicted*, and which features drive predictions? | $R^2 = 0.833$ (random split) vs. **0.425–0.547** (geographic holdout) |
++
++The paper's core methodological contribution is a systematic study of
++**spatial leakage** in hedonic model evaluation: random train/test splits let
++geographically proximate listings appear on both sides of the split, inflating
++performance metrics. Three complementary designs quantify the damage — a 10-state
++geographic holdout, a 6-stage feature-ablation cascade, and a latitude/longitude
++augmentation experiment.
++
++> ⚠️ **Interpretation caveat.** All estimates are *listing-price capitalization
++> gradients* — conditional associations between attributes and *asking* prices.
++> They are not causal willingness-to-pay parameters and not transaction-price
++> implicit prices.
++
++---
++
++## 🏆 Key Findings
++
++1. **Geography does the heavy lifting in OLS.** Moving from 4 Census-region
++   dummies to state fixed effects to 886 ZIP3 fixed effects raises out-of-sample
++   $R^2$ from 0.630 → 0.678 → 0.725 — a 9.5 pp gain from spatial granularity alone.
++
++2. **Strong, stable residual spatial autocorrelation.** Moran's $I$ on OLS
++   residuals averages **0.2745** (SD 0.0076) across three independent 5,000-listing
++   subsamples (row-standardized KNN weights, $k = 8$; all $p < 0.001$).
++
++3. **Mean effects mask distributional heterogeneity.** The garage gradient is
++   **10× larger** at $\tau = 0.10$ than at $\tau = 0.90$ ($z = 28.9$); the pool
++   premium only emerges above the median; the age penalty is concentrated in
++   lower-priced homes.
++
++4. **Random validation flatters machine learning.** XGBoost reaches $R^2 = 0.833$
++   under a random 80/20 split but only **0.425–0.547** when 10 entire states
++   (438,315 listings) are held out.
++
++5. **Geographic features can *hurt* generalization.** Removing all geographic
++   features *improves* geographic-holdout $R^2$ from 0.425 to **0.519**, while
++   adding raw lat/lon coordinates boosts random $R^2$ (+3.7 pp) but *degrades*
++   geographic holdout. Region dummies memorize training-set price levels.
++
++6. **SHAP rankings are model-stable but not structural.** Spearman rank
++   correlations of mean $|\phi|$ across XGBoost / LightGBM / Random Forest range
++   from **0.89 to 0.99**, with the same six features on top — yet these remain
++   predictive decompositions, not implicit prices.
++
++7. **Imputation matters.** The lot-size gradient **triples** (0.018 → 0.059) when
++   state-median-imputed lot sizes are dropped — a warning for hedonic work on
++   scraped listing data.
++
++---
++
++## 🗂 Repository Structure
++
++```
++wp3_uqo/
++├── README.md                      ← you are here
++├── AUDIT.md                       ← forensic audit of the original project archive
++├── CHANGES.md                     ← every move/refactor/fix made during restructuring
++├── requirements.txt               ← pinned Python dependencies (validated 2026-08-05)
++│
++├── data/                          ⚠ NOT in the Git repo (3.2 GB — see "Data" below)
++│   ├── raw/
++│   │   └── us_housing.duckdb      # raw Zillow extract (839,313 × 116 + 4 aux tables)
++│   └── processed/
++│       ├── analytical_sample.pkl  # final sample, 788,842 × 68 engineered columns
++│       ├── model_data.pkl         # standardized X (788,842 × 63), y, OLS fit, residuals
++│       └── shap_data.pkl          # TreeSHAP values (10,000 × 62) + explanation sample
++│
++├── src/wp3/                       # shared library code
++│   ├── config.py                  # paths (relative, WP3_ROOT-overridable), constants,
++│   │                              #   feature-block definitions, holdout states, seeds
++│   ├── data.py                    # loaders + 62-regressor design-matrix builder
++│   ├── models.py                  # XGBoost training helper (dual validation schemes)
++│   └── plotting.py                # journal figure style + human-readable variable labels
++│
++├── scripts/                       # numbered pipeline entry points
++│   ├── 01_spatial_robustness.py   # ZIP3 FE OLS · Moran's I ·  XGB ± geography · ablation
++│   ├── 02_qr_imputation.py        # QR stability · inter-quantile Wald · imputation ·
++│   │                              #   winsorization sensitivity
++│   ├── 03_make_figures.py         # regenerates all 11 figures + verification stats
++│   └── 04_export_tables.py        # exports paper tables → results/tables/*.csv
++│
++├── figures/                       # all 11 paper figures (PNG, 300 dpi, unified style)
++│
++├── results/
++│   ├── *.pkl                      ⚠ NOT in the Git repo (up to 437 MB)
++│   └── tables/                    # 13 CSVs mirroring the paper's tables (in repo)
++│
++└── paper/                         # LaTeX source
++    ├── main.tex                   # preamble + metadata + \input skeleton
++    ├── references.bib             # 37 BibTeX entries (natbib + apalike)
++    ├── sections/                  # one file per section (IMRaD + robustness)
++    │   ├── titlepage.tex          ├── introduction.tex   ├── literature.tex
++    │   ├── data.tex               ├── methodology.tex    ├── results.tex
++    │   ├── robustness.tex         ├── discussion.tex     ├── limitations.tex
++    │   └── conclusion.tex
++    ├── appendix/appendix.tex      # extra figures, full OLS table, reproducibility checklist
++    ├── Makefile                   # latexmk targets (all / clean / distclean)
++    ├── uq_logo.jpg
++    └── main.pdf                   # compiled paper — 52 pages, zero warnings
++```
++
++---
++
++## 💾 Data
++
++### What the data are
++
++- **Source:** Zillow active for-sale listings, 2025–2026 snapshot.
++- **Raw:** 839,313 residential properties × 116 variables, stored in a DuckDB
++  database (`properties`, `price_history`, `schools`, `tax_history`, `meta_columns`).
++- **Analytical sample:** 788,842 listings after five sequential filters
++  (valid price \$10K–\$10M, living area 200–20,000 sqft, 1–10 beds/baths,
++  valid coordinates, US states + DC only — 6.0 % attrition).
++- **68 engineered columns:** log transforms, age & age², ratios, amenity dummies,
++  neighborhood scores, market-status flags, 6 interaction terms, and simplified
++  categoricals (roof / construction / foundation / region).
++
++### Why the data are not in this Git repository
++
++GitHub rejects files above 100 MB. The DuckDB file is **1.6 GB** and the processed
++pickles reach **867 MB**, so `data/` and `results/*.pkl` are excluded via
++`.gitignore`. The canonical copies live in the local research archive:
++
++| Artifact | Size | Location |
++|---|---|---|
++| `us_housing.duckdb` | 1.6 GB | `data/raw/` (local) |
++| `analytical_sample.pkl` | 457 MB | `data/processed/` (local) |
++| `model_data.pkl` | 867 MB | `data/processed/` (local) |
++| `ml_results.pkl` | 437 MB | `results/` (local) |
++| `shap_data.pkl`, `qr_results.pkl`, `extended_results.pkl`, `v3_*.pkl` | < 10 MB each | `results/` (local; small ones could be added on request) |
++
++📬 **Data access:** available on request (subject to Zillow Terms of Service) —
++**contact@spboucher.ai**.
++
++---
++
++## 🧪 Methodology at a Glance
++
++| Component | Specification |
++|---|---|
++| Dependent variable | $\ln(\text{listing price})$ |
++| OLS | 62 regressors, standardized + unstandardized variants, **HC3** robust SE |
++| Fixed effects | Census region (baseline) → state (50) → ZIP3 (886) |
++| Quantile regression | statsmodels `QuantReg`, $\tau \in \{0.10,\ldots,0.90\}$, 150,000-obs subsample, 10-seed stability check |
++| Inter-quantile tests | Wald $z$-tests on $\hat\beta(0.10)-\hat\beta(0.90)$ |
++| XGBoost | 1,000 trees, depth 8, lr 0.05, subsample/colsample 0.8, early stopping 50 |
++| LightGBM / RF / Ridge / Lasso / Elastic Net | benchmark suite |
++| Validation | random 80/20 (seed 42) **and** 10-state geographic holdout (CA NY TX FL OH CO NC WA IL GA — 438,315 test obs) |
++| Ablation | 6 nested feature sets: structural → +lot → +amenities → +neighborhood → +market → full |
++| Interpretation | TreeSHAP on 10,000 test obs; cross-model Spearman stability (XGB/LGB/RF) |
++| Spatial diagnostics | Moran's $I$, row-standardized KNN ($k=8$), 3 × 5,000-obs subsamples, 999 permutations |
++| Sensitivity | state-median-imputation drop-out, lot-size winsorization (p99.5), Bike Score cap |
++
++---
++
++## 🔁 The Analysis Pipeline
++
++```
++us_housing.duckdb  (raw, 839,313 listings)
++        │
++        │  [sample construction & feature engineering — original script lost;
++        │   the stored analytical_sample.pkl is the canonical artifact]
++        ▼
++analytical_sample.pkl  (788,842 × 68)
++        │
++        ├─ [estimation — original scripts lost; stored artifacts are canonical]
++        │      ├── model_data.pkl        (standardized X, OLS fit, residuals)
++        │      ├── qr_results.pkl        (QR params at 5 quantiles)
++        │      ├── ml_results.pkl        (fitted XGB/LGBM + test predictions)
++        │      ├── shap_data.pkl         (TreeSHAP values, 10,000 × 62)
++        │      ├── extended_results.pkl  (unstandardized OLS, geo holdout, RF)
++        │      └── v3_shap_stability.pkl (XGB/LGB/RF SHAP rank correlations)
++        │
++        ├─ scripts/01_spatial_robustness.py ──► results/v3_spatial_results.pkl
++        ├─ scripts/02_qr_imputation.py ───────► results/v3_qr_imputation_results.pkl
++        ├─ scripts/03_make_figures.py ────────► figures/fig1…fig11 (+ verification)
++        └─ scripts/04_export_tables.py ───────► results/tables/*.csv
++                                                       │
++                                                       ▼
++                                          paper/main.tex ──► main.pdf (52 p.)
++```
++
++The bracketed upstream stages were produced before this restructuring by scripts
++that no longer exist (see [Project History](#-project-history--provenance)); their
++outputs are preserved and every downstream number is verified against them.
++
++---
++
++## ⚙️ Installation & Setup
++
++**Prerequisites:** Python ≥ 3.11, a TeX Live distribution (with `newtx`, `natbib`,
++`booktabs`, `threeparttable`), and ~4 GB of free disk for the data artifacts.
++
++```bash
++git clone https://github.com/spboucher-ai/wp3-hedonic-housing-us.git
++cd wp3-hedonic-housing-us
++
++python3 -m venv .venv
++source .venv/bin/activate
++pip install -r requirements.txt
++```
++
++Then place the data artifacts (request them at **contact@spboucher.ai**) into
++`data/raw/`, `data/processed/`, and `results/` as shown in
++[Repository Structure](#-repository-structure).
++
++All paths resolve relative to the repository root. To point the code at another
++location, set the environment variable:
++
++```bash
++export WP3_ROOT=/path/to/artifacts
++```
++
++---
++
++## ▶️ Reproducing the Results
++
++| Step | Command | Runtime* | Needs |
++|---|---|---|---|
++| Spatial & robustness suite | `python scripts/01_spatial_robustness.py` | ~1–2 h (trains 16 XGBoost models) | `analytical_sample.pkl` |
++| QR & sensitivity suite | `python scripts/02_qr_imputation.py` | ~1–3 h (12 quantile regressions on 150k obs) | `model_data.pkl`, DuckDB |
++| **All 11 figures** | `python scripts/03_make_figures.py` | ~5 min | processed pickles |
++| Single figures | `python scripts/03_make_figures.py --figs fig2 fig4` | seconds–minutes | idem |
++| **CSV table exports** | `python scripts/04_export_tables.py` | ~2 min | result pickles |
++
++\* Apple Silicon, 32 GB RAM; scripts use all cores (`n_jobs=-1`).
++
++Every script prints **verification statistics** comparing recomputed values with
++the numbers reported in the paper (see [Verification](#-verification--integrity)).
++
++---
++
++## 📄 Building the Paper
++
++```bash
++cd paper
++latexmk          # pdflatex ×N + bibtex, via Makefile/latexmkrc defaults
++# or: make       # same thing
++# or: make clean / make distclean
++```
++
++- Output: `paper/main.pdf` — **52 pages**, compiles with **zero errors, zero
++  undefined references/citations**.
++- Figures are pulled from `../figures/` via `\graphicspath`.
++- Bibliography: `paper/references.bib` (37 entries), `natbib` + `apalike`.
++- Metadata (title, abstract, keywords R31/C21/C45/C52, version) is centralized in
++  `main.tex` `\WP*` macros.
++
++---
++
++## 🖼 Figures
++
++All figures are regenerated from the stored artifacts by `scripts/03_make_figures.py`
++in a unified publication style (serif typography matched to the paper's `newtx`
++text font, muted colorblind-safe palette, no chart junk, 300 dpi).
++
++| # | File | Content | Built from |
++|---|---|---|---|
++| 1 | `fig1_price_distribution.png` | Price & log-price histograms with medians | `analytical_sample.pkl` |
++| 2 | `fig2_ols_diagnostics.png` | Residuals-vs-fitted, Q-Q, density, scale-location | `model_data.pkl` |
++| 3 | `fig3_quantile_coefficients.png` | QR coefficient paths vs. OLS benchmark (8 panels) | `qr_results.pkl` + `model_data.pkl` |
++| 4 | `fig4_model_comparison.png` | Predicted vs. actual: OLS / XGBoost / LightGBM | `ml_results.pkl` |
++| 5 | `fig5_shap_summary.png` | SHAP beeswarm, top 20 features | `shap_data.pkl` |
++| 6 | `fig6_shap_importance.png` | Mean \|SHAP\| bar chart, top 20 | `shap_data.pkl` |
++| 7 | `fig7_geographic_prices.png` | 50,000-listing national price map (lat/lon, viridis) | `analytical_sample.pkl` |
++| 8 | `fig8_regional_prices.png` | Log-price boxplots by Census region (with N) | `analytical_sample.pkl` |
++| 9 | `fig9_marginal_effects.png` | Bivariate scatters + binned means (6 attributes) | `analytical_sample.pkl` |
++| 10 | `fig10_shap_dependence.png` | SHAP dependence, 8 key features | `shap_data.pkl` |
++| 11 | `fig11_shap_interactions.png` | SHAP for interaction terms (waterfront×sqft, pool×South) | `shap_data.pkl` |
++
++---
++
++## 📊 Results Summary
++
++**Predictive performance (log-price scale):**
++
++| Model | Random $R^2$ | Geo-holdout $R^2$ | RMSE (random) |
++|---|---:|---:|---:|
++| OLS (62 regressors) | 0.630 | < 0 | 0.491 |
++| OLS + State FE | 0.678 | — | 0.459 |
++| OLS + ZIP3 FE | 0.725 | — | 0.423 |
++| Random Forest | 0.784 | 0.542 | 0.375 |
++| LightGBM | 0.809 | — | 0.353 |
++| **XGBoost** | **0.833** | **0.547** | **0.330** |
++| XGBoost, no geographic features | 0.830 | **0.519** | — |
++| XGBoost + lat/lon | 0.870 | 0.464 | — |
++| XGBoost (ablation variant, full 62) | 0.833 | 0.425 | — |
++
++**Ablation cascade (XGBoost):** structural 0.498 → +lot 0.546 → +amenities 0.638 →
+++neighborhood **0.814 (+17.6 pp)** → +market 0.824 → full 0.833 (random $R^2$).
++
++**Machine-readable versions** of these and all other paper tables are in
++[`results/tables/`](results/tables/) (13 CSV files: OLS coefficients, QR paths,
++inter-quantile Wald tests, stability CVs, Moran's I, imputation/winsorization
++sensitivity, SHAP importance & cross-model correlations, ZIP3 FE, ablation).
++
++---
++
++## ✅ Verification & Integrity
++
++The restructuring included a systematic audit reconciling the manuscript against
++the stored result artifacts. Highlights:
++
++- **Exact matches** — OLS residual diagnostics (skewness 0.18, kurtosis 5.55,
++  Jarque–Bera 217,078), test-set $R^2$ (OLS 0.6301, XGBoost 0.8330,
++  LightGBM 0.8088), Moran's $I$ subsample values and mean/SD, QR coefficients at
++  all five quantiles, and the OLS reference line (0.312) in Figure 3.
++- **End-to-end reproduction** — re-running the refactored Moran's $I$ pipeline
++  reproduces the stored values to 4 decimal places (0.2742 / 0.2839 / 0.2652).
++- **Manuscript corrections** — six internal inconsistencies were found and fixed
++  (wrong KNN $k$ in the text, mislabeled inter-quantile sign convention,
++  winsorization description not matching the actual procedure, a duplicated table
++  row, mixed in/out-of-sample $R^2$ in the summary matrix). Every fix aligns the
++  text to the stored results and is itemized in [`CHANGES.md`](CHANGES.md) §4.
++  **No scientific result was altered.**
++- **Completed placeholders** — 13 `[TODO]` table cells in the original manuscript
++  were filled with the exact values from the result pickles.
++
++See [`AUDIT.md`](AUDIT.md) for the full audit and [`CHANGES.md`](CHANGES.md) for
++the change log.
++
++---
++
++## 🕰 Project History & Provenance
++
++- The project was completed in **May 2026** in a flat working folder
++  (`immo-wp3-spb-20260519`), then restructured into this compendium on
++  **2026-08-05**. The original archive is preserved untouched.
++- The scripts that built the analytical sample and estimated the primary models
++  (OLS/QR/ML/SHAP) were **lost** prior to restructuring; only two robustness
++  scripts survived and were refactored into `scripts/01` and `scripts/02`. The
++  stored pickles are the canonical record of those stages and every downstream
++  number is validated against them.
++- Five paper figures had been deleted from the archive; they were rebuilt from the
++  stored data, and subsequently **all 11 figures** were regenerated in a unified
++  journal style.
++- Three earlier monolithic drafts (`paper_hedonic_pricing{,_v2,_v3}.tex`) precede
++  the sectioned `wp3/` source that became `paper/`.
++
++---
++
++## 📖 Citation
++
++If you use this code, the figures, or the results, please cite:
++
++```bibtex
++@techreport{boucher2026hedonic,
++  author      = {Boucher, Simon-Pierre},
++  title       = {Hedonic Housing Price Models for the United States:
++                 A Multi-Method Comparison of Parametric, Quantile,
++                 and Machine Learning Approaches},
++  institution = {Universit\'e du Qu\'ebec en Outaouais,
++                 D\'epartement des sciences administratives},
++  type        = {Working Paper},
++  number      = {3},
++  year        = {2026},
++  month       = {May}
++}
++```
++
++---
++
++## 📬 Contact & License
++
++**Simon-Pierre Boucher**
++Département des sciences administratives
++Université du Québec en Outaouais — Gatineau (Québec), Canada
++📧 **contact@spboucher.ai** · 🎓 simon-pierre.boucher@uqo.ca
++
++© 2026 Simon-Pierre Boucher. Analysis code is shared for **replication and review**
++purposes. The underlying Zillow data are subject to Zillow's Terms of Service and
++are **not redistributed** in this repository; the paper (`paper/main.pdf`) is a
++working paper — please cite rather than redistribute.
++
++<div align="center">
++<sub>Built with Python · XGBoost · LightGBM · statsmodels · SHAP · DuckDB · LaTeX — reproducible from stored artifacts end to end.</sub>
++</div>

added figures/fig10_shap_dependence.png +0 −0

Binary file not shown.

added figures/fig11_shap_interactions.png +0 −0

Binary file not shown.

added figures/fig1_price_distribution.png +0 −0

Binary file not shown.

added figures/fig2_ols_diagnostics.png +0 −0

Binary file not shown.

added figures/fig3_quantile_coefficients.png +0 −0

Binary file not shown.

added figures/fig4_model_comparison.png +0 −0

Binary file not shown.

added figures/fig5_shap_summary.png +0 −0

Binary file not shown.

added figures/fig6_shap_importance.png +0 −0

Binary file not shown.

added figures/fig7_geographic_prices.png +0 −0

Binary file not shown.

added figures/fig8_regional_prices.png +0 −0

Binary file not shown.

added figures/fig9_marginal_effects.png +0 −0

Binary file not shown.

added paper/Makefile +11 −0

++.PHONY: all clean distclean
++
++all:
++	latexmk
++
++clean:
++	latexmk -c
++
++distclean:
++	latexmk -C
++	rm -f *.synctex.gz *.run.xml *.bbl *.bcf

added paper/appendix/appendix.tex +165 −0

++% Author: Simon-Pierre Boucher — contact@spboucher.ai
++%
++% ═══════════════════════════════════════════════════════════════════════
++% APPENDICES
++% ═══════════════════════════════════════════════════════════════════════
++\appendix
++
++\section{Additional Figures}
++\label{app:figures}
++
++\begin{figure}[H]
++    \centering
++    \includegraphics[width=0.85\textwidth]{figures/fig6_shap_importance.png}
++    \caption{Feature Importance Bar Chart: Mean Absolute SHAP Values (XGBoost). These values reflect predictive contributions, not causal importance.}
++    \label{fig:shap_bar}
++\end{figure}
++
++\begin{figure}[H]
++    \centering
++    \includegraphics[width=\textwidth]{figures/fig11_shap_interactions.png}
++    \caption{SHAP Values for Interaction Terms: (a) Waterfront $\times$ Log(Living Area); (b) Pool $\times$ South Region}
++    \label{fig:shap_interactions}
++\end{figure}
++
++
++\section{Full OLS Coefficient Table}
++\label{app:ols_full}
++
++Table~\ref{tab:ols_full} reports the complete set of standardized OLS coefficients, including all categorical controls.
++
++\begin{landscape}
++\begin{table}[H]
++\centering
++\caption{Full OLS Regression Results Including All Categorical Controls (Standardized)}
++\label{tab:ols_full}
++\begin{threeparttable}
++\footnotesize
++\begin{tabular}{lrrlclrrl}
++\toprule
++Variable & Coeff. & SE & Sig. & & Variable & Coeff. & SE & Sig. \\
++\midrule
++Constant & 12.510 & 0.010 & *** & & Roof: Metal & 0.070 & 0.008 & *** \\
++$\ln$(Living Area)$^\dagger$ & 0.312 & 0.003 & *** & & Roof: Shingle/Comp & $-$0.074 & 0.008 & *** \\
++Bedrooms$^\dagger$ & $-$0.068 & 0.002 & *** & & Roof: Tile & $-$0.110 & 0.008 & *** \\
++Bathrooms$^\dagger$ & 0.236 & 0.003 & *** & & Roof: Slate & 0.008 & 0.017 & \\
++Age$^\dagger$ & $-$0.042 & 0.014 & ** & & Roof: Other & 0.033 & 0.008 & *** \\
++Age$^{2\dagger}$ & 0.051 & 0.002 & *** & & Roof: Unknown & 0.004 & 0.008 & \\
++Stories$^\dagger$ & 0.000 & 0.000 & & & Constr: Concrete/Block & 0.269 & 0.003 & *** \\
++Bath/Bed Ratio$^\dagger$ & $-$0.021 & 0.002 & *** & & Constr: Stucco & 0.149 & 0.002 & *** \\
++Sqft/Bed$^\dagger$ & $-$0.002 & 0.002 & & & Constr: Stone & 0.145 & 0.005 & *** \\
++$\ln$(Lot Size)$^\dagger$ & 0.070 & 0.001 & *** & & Constr: Wood/Frame & 0.103 & 0.002 & *** \\
++Pool & 0.029 & 0.003 & *** & & Constr: Vinyl & 0.012 & 0.002 & *** \\
++Spa & 0.033 & 0.003 & *** & & Constr: Steel & 0.027 & 0.014 & * \\
++Basement & $-$0.042 & 0.002 & *** & & Constr: Other & 0.075 & 0.002 & *** \\
++Fireplace & $-$0.002 & 0.002 & & & Constr: Unknown & 0.177 & 0.002 & *** \\
++Garage & 0.109 & 0.002 & *** & & Found: Concrete & 0.217 & 0.005 & *** \\
++Waterfront & $-$0.135 & 0.032 & *** & & Found: Crawlspace & 0.181 & 0.006 & *** \\
++Central Air & 0.069 & 0.001 & *** & & Found: Slab & 0.122 & 0.005 & *** \\
++Forced Air & $-$0.023 & 0.002 & *** & & Found: Pier/Raised & 0.161 & 0.006 & *** \\
++Hardwood & 0.125 & 0.001 & *** & & Found: Stone & 0.032 & 0.010 & ** \\
++Parking$^\dagger$ & 0.000 & 0.099 & & & Found: Other & 0.144 & 0.006 & *** \\
++Luxury$^\dagger$ & 0.044 & 0.002 & *** & & Found: Unknown & 0.174 & 0.005 & *** \\
++Walk$^\dagger$ & $-$0.011 & 0.001 & *** & & Northeast & 0.487 & 0.003 & *** \\
++Bike$^\dagger$ & 0.072 & 0.001 & *** & & South & 0.022 & 0.003 & *** \\
++Transit$^\dagger$ & 0.052 & 0.001 & *** & & West & 0.401 & 0.003 & *** \\
++School Rating$^\dagger$ & $-$0.049 & 0.001 & *** & & sqft$\times$Age$^\dagger$ & $-$0.110 & 0.014 & *** \\
++School Count$^\dagger$ & $-$0.002 & 0.001 & *** & & Pool$\times$South & 0.008 & 0.001 & *** \\
++School Dist.$^\dagger$ & $-$0.016 & 0.001 & *** & & WF$\times$sqft$^\dagger$ & 0.137 & 0.009 & *** \\
++Tax Rate$^\dagger$ & $-$0.029 & 0.001 & *** & & Base$\times$North & $-$0.025 & 0.001 & *** \\
++Condo & $-$0.037 & 0.004 & *** & & Condo$\times$Walk$^\dagger$ & 0.082 & 0.001 & *** \\
++HOA & $-$0.108 & 0.002 & *** & & Age$\times$Lux$^\dagger$ & 0.044 & 0.001 & *** \\
++$\ln$(HOA+1)$^\dagger$ & 0.044 & 0.001 & *** & & & & & \\
++New Constr. & 0.103 & 0.003 & *** & & & & & \\
++Foreclosure & $-$0.406 & 0.010 & *** & & & & & \\
++\midrule
++\multicolumn{9}{l}{$R^2 = 0.634$, Adj.\ $R^2 = 0.634$, $N = 788{,}842$, $F = 18{,}712.5$, RMSE $= 0.489$} \\
++\bottomrule
++\end{tabular}
++\begin{tablenotes}
++\footnotesize
++\item \textit{Notes:} HC3 robust standard errors. $^\dagger$Standardized continuous variables. Reference categories: Roof = Flat; Construction = Brick; Foundation = Basement; Region = Midwest. *** $p<0.001$, ** $p<0.01$, * $p<0.05$.
++\end{tablenotes}
++\end{threeparttable}
++\end{table}
++\end{landscape}
++
++
++\section{Robustness Agenda}
++\label{app:robustness_agenda}
++
++The following robustness checks and extensions are planned or completed. Items marked with $\checkmark$ have been completed in this version; unmarked items are left for future work.
++
++\begin{enumerate}[nosep]
++    \item[$\checkmark$] ZIP3-level fixed effects (Section~\ref{sec:progressive_fe}).
++    \item County-level and MSA-level fixed effects.
++    \item Spatial lag and spatial error model estimation.
++    \item Spatial cross-validation (train on some regions, test on others) at finer geographic levels.
++    \item[$\checkmark$] Inter-quantile Wald tests for coefficient equality across quantiles (Section~\ref{sec:qr_results}).
++    \item[$\checkmark$] Re-estimation excluding imputed observations (Section~\ref{sec:imputation_sensitivity}).
++    \item CatBoost benchmark with native categorical handling.
++    \item Nested cross-validation for hyperparameter tuning.
++    \item[$\checkmark$] SHAP stability comparison across XGBoost, LightGBM, and Random Forest (Section~\ref{sec:shap_results}).
++    \item Integration of climate risk data from First Street Foundation or FEMA flood maps.
++    \item Replication using transaction prices from recently sold listings.
++    \item GAM/spline models to decompose the ML gain into non-linearity versus spatial partitioning.
++    \item Comparison of sample distribution to ACS and Census benchmarks by state and price tier.
++    \item Calibration plots by price decile for all models.
++    \item[$\checkmark$] Winsorization sensitivity (Section~\ref{sec:winsorization}).
++    \item[$\checkmark$] Feature ablation analysis for XGBoost (Section~\ref{sec:ablation}).
++    \item[$\checkmark$] XGBoost with latitude/longitude coordinates (Section~\ref{sec:geo_features}).
++    \item[$\checkmark$] XGBoost without geographic features (Section~\ref{sec:geo_features}).
++    \item[$\checkmark$] Moran's $I$ subsample stability (Section~\ref{sec:spatial_autocorrelation}).
++    \item[$\checkmark$] Quantile regression stability across 10 subsamples (Section~\ref{sec:qr_stability}).
++\end{enumerate}
++
++
++\section{Reproducibility Checklist}
++\label{app:reproducibility}
++
++\begin{table}[H]
++\centering
++\caption{Reproducibility Checklist}
++\label{tab:reproducibility}
++\begin{threeparttable}
++\small
++\begin{tabular}{p{6cm}p{3cm}p{4cm}}
++\toprule
++Item & Status & Notes \\
++\midrule
++\multicolumn{3}{l}{\textit{Data}} \\
++Data source identified & Yes & Zillow active listings \\
++Sample construction documented & Yes & Table~\ref{tab:attrition} \\
++Missing data rates reported & Yes & Table~\ref{tab:missing} \\
++Imputation method documented & Yes & State-level medians \\
++Imputation sensitivity tested & Yes & Table~\ref{tab:imputation} \\
++\midrule
++\multicolumn{3}{l}{\textit{Methodology}} \\
++Model specifications documented & Yes & Eq.~\ref{eq:ols}--\ref{eq:moran} \\
++Hyperparameters reported & Yes & Section~\ref{sec:methodology} \\
++Random seeds reported & Yes & Seed = 42 \\
++Validation design documented & Yes & Section~\ref{sec:validation_designs} \\
++\midrule
++\multicolumn{3}{l}{\textit{Results}} \\
++Point estimates reported & Yes & Tables~\ref{tab:ols_results}--\ref{tab:shap_stability} \\
++Standard errors / CIs reported & Yes (OLS, QR) & HC3 standard errors \\
++Multiple comparisons addressed & Partially & Inter-quantile tests \\
++Effect sizes in natural units & Yes & Table~\ref{tab:ols_unstd} \\
++\midrule
++\multicolumn{3}{l}{\textit{Robustness}} \\
++Sensitivity to data quality & Yes & Sections~\ref{sec:imputation_sensitivity}--\ref{sec:winsorization} \\
++Sensitivity to model choice & Yes & Table~\ref{tab:ml_comparison} \\
++Sensitivity to validation design & Yes & Tables~\ref{tab:geo_holdout}--\ref{tab:geo_role} \\
++Cross-model stability & Yes & Table~\ref{tab:shap_stability} \\
++\midrule
++\multicolumn{3}{l}{\textit{Code and Data Availability}} \\
++Code available & Yes & Replication package (\texttt{src/}, \texttt{scripts/}, pinned \texttt{requirements.txt}) \\
++Data available & On request & Subject to Zillow ToS \\
++\bottomrule
++\end{tabular}
++\begin{tablenotes}
++\small
++\item \textit{Notes:} This checklist follows recommended practices for empirical reproducibility in applied economics.
++\end{tablenotes}
++\end{threeparttable}
++\end{table}

added paper/main.pdf +0 −0

Binary file not shown.

added paper/main.tex +201 −0

++% Author: Simon-Pierre Boucher — contact@spboucher.ai
++%
++% ============================================================================
++% UQO Working Paper No. 3
++% Hedonic Housing Price Models for the United States: A Multi-Method
++% Comparison of Parametric, Quantile, and Machine Learning Approaches
++% ============================================================================
++\documentclass[12pt,letterpaper]{article}
++
++% --- Encoding & Language ---
++\usepackage[utf8]{inputenc}
++\usepackage[T1]{fontenc}
++\usepackage[english]{babel}
++
++% --- Page Layout ---
++\usepackage[letterpaper, margin=1in, headheight=15pt]{geometry}
++\usepackage{setspace}
++\onehalfspacing
++\setlength{\parindent}{1.5em}
++\setlength{\parskip}{0pt}
++
++% --- Typography ---
++\usepackage{newtxtext,newtxmath}
++\usepackage{amsmath,amsfonts}
++\let\Bbbk\relax
++\usepackage{amssymb}
++\usepackage{mathtools}
++\usepackage{microtype}
++
++% --- Tables ---
++\usepackage{booktabs}
++\usepackage{threeparttable}
++\usepackage{tabularx}
++\usepackage{array}
++\usepackage{multirow}
++\usepackage{longtable}
++\usepackage{adjustbox}
++\usepackage{siunitx}
++\usepackage{dcolumn}
++
++% --- Figures ---
++\usepackage{graphicx}
++\graphicspath{{./}{../}}  % figures live in ../figures/, logo in ./
++\usepackage[
++  font       = small,
++  labelfont  = bf,
++  labelsep   = period,
++  skip       = 8pt,
++  justification = justified,
++  singlelinecheck = false
++]{caption}
++\usepackage{subcaption}
++\usepackage{float}
++\usepackage{pdflscape}
++
++% --- Colors & Links ---
++\usepackage[dvipsnames]{xcolor}
++\definecolor{linkblue}{RGB}{0,51,102}
++\usepackage[bookmarks, bookmarksnumbered]{hyperref}
++\hypersetup{
++  colorlinks  = true,
++  linkcolor   = NavyBlue,
++  citecolor   = NavyBlue,
++  urlcolor    = NavyBlue,
++  pdftitle    = {Hedonic Housing Price Models for the United States: A Multi-Method Comparison of Parametric, Quantile, and Machine Learning Approaches},
++  pdfauthor   = {Simon-Pierre Boucher}
++}
++
++% --- Bibliography ---
++\usepackage[round, authoryear, comma]{natbib}
++\setcitestyle{aysep={,}}
++\bibliographystyle{apalike}
++
++% --- Headers & Footers ---
++\usepackage{fancyhdr}
++\pagestyle{fancy}
++\fancyhf{}
++\fancyhead[L]{\small\itshape Hedonic Housing Price Models for the United States}
++\fancyhead[R]{\small\thepage}
++\renewcommand{\headrulewidth}{0.4pt}
++\renewcommand{\footrulewidth}{0pt}
++\fancypagestyle{plain}{%
++  \fancyhf{}
++  \fancyfoot[C]{\small\thepage}
++  \renewcommand{\headrulewidth}{0pt}
++}
++
++% --- Section Formatting ---
++\usepackage{titlesec}
++\titleformat{\section}{\large\bfseries}{\thesection.}{0.5em}{}
++\titleformat{\subsection}{\normalsize\bfseries}{\thesubsection.}{0.5em}{}
++\titleformat{\subsubsection}{\normalsize\itshape}{\thesubsubsection.}{0.5em}{}
++
++% --- Appendix Support ---
++\usepackage[toc, page]{appendix}
++\usepackage{enumitem}
++\usepackage{etoolbox}
++\usepackage[hang,flushmargin]{footmisc}
++
++% --- Custom Column Types ---
++\newcolumntype{R}[1]{>{\raggedleft\arraybackslash}p{#1}}
++\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}
++\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}
++\newcolumntype{d}[1]{D{.}{.}{#1}}
++
++% --- Custom Commands ---
++\newcommand{\sym}[1]{\ensuremath{^{#1}}}
++\newcommand{\stmark}[1]{\rlap{\textsuperscript{#1}}}
++\DeclareMathOperator*{\plim}{plim}
++\newcommand{\E}{\mathbb{E}}
++\newcommand{\Var}{\mathrm{Var}}
++\newcommand{\Cov}{\mathrm{Cov}}
++\newcommand{\Corr}{\mathrm{Corr}}
++\newcommand{\se}{\mathrm{s.e.}}
++\newcommand{\tr}{\mathrm{tr}}
++\newcommand{\rank}{\mathrm{rank}}
++\newcommand{\diag}{\mathrm{diag}}
++\newcommand{\R}{\mathbb{R}}
++\newcommand{\N}{\mathbb{N}}
++\newcommand{\eps}{\varepsilon}
++\newcommand{\bfbeta}{\boldsymbol{\beta}}
++\newcommand{\bfgamma}{\boldsymbol{\gamma}}
++\newcommand{\bfalpha}{\boldsymbol{\alpha}}
++\newcommand{\bfdelta}{\boldsymbol{\delta}}
++\newcommand{\bftheta}{\boldsymbol{\theta}}
++\newcommand{\bfSigma}{\boldsymbol{\Sigma}}
++\newcommand{\bfOmega}{\boldsymbol{\Omega}}
++\newcommand{\bfX}{\mathbf{X}}
++\newcommand{\bfY}{\mathbf{Y}}
++\newcommand{\bfy}{\mathbf{y}}
++\newcommand{\bfe}{\mathbf{e}}
++\newcommand{\bfs}{\mathbf{s}}
++\newcommand{\iid}{\overset{\mathrm{iid}}{\sim}}
++\newcommand{\pto}{\overset{p}{\to}}
++\newcommand{\dto}{\overset{d}{\to}}
++\newcommand{\ols}{\mathrm{OLS}}
++\newcommand{\iv}{\mathrm{IV}}
++\newcommand{\gmm}{\mathrm{GMM}}
++\newcommand{\mle}{\mathrm{MLE}}
++\newcommand{\pval}{\textit{p}-value}
++\newcommand{\tstat}{\textit{t}-statistic}
++\newcommand{\fstat}{\textit{F}-statistic}
++\newcommand{\tablenote}[1]{\begin{minipage}{\linewidth}\footnotesize #1\end{minipage}}
++\newcommand{\signote}{*** $p < 0.001$; ** $p < 0.01$; * $p < 0.05$.}
++
++% ============================================================================
++% METADATA
++% ============================================================================
++\newcommand{\WPnumber}{3}
++\newcommand{\WPtitle}{Hedonic Housing Price Models for the United States: A Multi-Method Comparison of Parametric, Quantile, and Machine Learning Approaches}
++\newcommand{\WPsubtitle}{}
++\newcommand{\WPdate}{May 2026}
++\newcommand{\WPversion}{1.0}
++\newcommand{\WPabstract}{%
++This paper compares econometric and machine-learning approaches to hedonic housing valuation using 788,842 active Zillow listings across all 50 U.S.\ states and the District of Columbia. A semi-log OLS model with 62 regressors ($R^2 = 0.634$) provides interpretable listing-price gradients; adding ZIP3 fixed effects raises $R^2$ to 0.725, and Moran's $I = 0.27$ confirms strong residual spatial autocorrelation. Quantile regression reveals distributional heterogeneity, with inter-quantile Wald tests rejecting coefficient equality between $\tau = 0.10$ and $\tau = 0.90$ for 11 of 13 key variables. XGBoost achieves $R^2 = 0.833$ under random validation but only 0.425 under state-level geographic holdout; ablation analysis traces the predictive gain primarily to neighborhood-quality features ($+17.6$ pp) and shows that removing geographic features \emph{improves} geographic holdout $R^2$ to 0.519, revealing spatial overfitting. SHAP importance rankings are stable across models (Spearman $\rho > 0.89$). Robustness checks confirm that the lot-size gradient triples when imputed observations are dropped, while other coefficients remain stable under winsorization and subsampling. Throughout, estimates are interpreted as conditional associations in listing prices, not causal willingness-to-pay parameters.%
++}
++\newcommand{\WPkeywords}{hedonic pricing, housing markets, quantile regression, XGBoost, SHAP, spatial autocorrelation, geographic validation}
++\newcommand{\WPjel}{R31, C21, C45, C52}
++
++% --- Author ---
++\newcommand{\WPauthor}{Simon-Pierre Boucher}
++\newcommand{\WPaffiliation}{%
++  D\'epartement des sciences administratives\\
++  Universit\'e du Qu\'ebec en Outaouais%
++}
++\newcommand{\WPemail}{simon-pierre.boucher@uqo.ca}
++\newcommand{\WPaddress}{%
++  Gatineau -- Pavillon Alexandre-Tach\'e\\
++  283, boulevard Alexandre-Tach\'e\\
++  Gatineau, Qu\'ebec, Canada J9A 1L8%
++}
++
++% ============================================================================
++% DOCUMENT
++% ============================================================================
++\begin{document}
++
++% --- Title Page ---
++\input{sections/titlepage}
++
++% --- Main Body ---
++\input{sections/introduction}
++\input{sections/literature}
++\input{sections/data}
++\input{sections/methodology}
++\input{sections/results}
++\input{sections/robustness}
++\input{sections/discussion}
++\input{sections/limitations}
++\input{sections/conclusion}
++
++% --- References ---
++\newpage
++\addcontentsline{toc}{section}{References}
++\bibliography{references}
++
++% --- Appendix ---
++\newpage
++\input{appendix/appendix}
++
++\end{document}

added paper/references.bib +364 −0

++Author: Simon-Pierre Boucher --- contact (at) spboucher.ai
++Bibliography for UQO Working Paper No. 3, converted from the manual
++thebibliography environment with identical keys. Note: BibTeX has no
++comment character; text outside entries is ignored, and a literal
++at-sign cannot appear here.
++
++@article{anglin1996semiparametric,
++  author  = {Anglin, Paul M. and Gen{\c{c}}ay, Ramazan},
++  title   = {Semiparametric estimation of a hedonic price function},
++  journal = {Journal of Applied Econometrics},
++  year    = {1996},
++  volume  = {11},
++  number  = {6},
++  pages   = {633--648},
++}
++
++@article{anselin2010thirty,
++  author  = {Anselin, Luc},
++  title   = {Thirty years of spatial econometrics},
++  journal = {Papers in Regional Science},
++  year    = {2010},
++  volume  = {89},
++  number  = {1},
++  pages   = {3--25},
++}
++
++@article{baldauf2020does,
++  author  = {Baldauf, Markus and Garlappi, Lorenzo and Yannelis, Constantine},
++  title   = {Does climate change affect real estate prices? {O}nly if you believe in it},
++  journal = {Review of Financial Studies},
++  year    = {2020},
++  volume  = {33},
++  number  = {3},
++  pages   = {1256--1295},
++}
++
++@article{bourassa2019machine,
++  author  = {Bourassa, Steven C. and Cantoni, Eva and Hoesli, Martin},
++  title   = {Predicting house prices with spatial dependence: {A} comparison of alternative methods},
++  journal = {Journal of Real Estate Research},
++  year    = {2019},
++  volume  = {32},
++  number  = {2},
++  pages   = {139--159},
++}
++
++@article{campbell2011forced,
++  author  = {Campbell, John Y. and Giglio, Stefano and Pathak, Parag},
++  title   = {Forced sales and house prices},
++  journal = {American Economic Review},
++  year    = {2011},
++  volume  = {101},
++  number  = {5},
++  pages   = {2108--2131},
++}
++
++@article{can1992specification,
++  author  = {Can, Ayse},
++  title   = {Specification and estimation of hedonic housing price models},
++  journal = {Regional Science and Urban Economics},
++  year    = {1992},
++  volume  = {22},
++  number  = {3},
++  pages   = {453--474},
++}
++
++@inproceedings{chen2016xgboost,
++  author    = {Chen, Tianqi and Guestrin, Carlos},
++  title     = {{XGBoost}: {A} scalable tree boosting system},
++  booktitle = {Proceedings of the 22nd {ACM} {SIGKDD}},
++  year      = {2016},
++  pages     = {785--794},
++}
++
++@article{chen2020housing,
++  author  = {Chen, Jian and Hu, Maggie and Lin, Zhenguo},
++  title   = {Housing price prediction using machine learning: {A} systematic review},
++  journal = {Expert Systems with Applications},
++  year    = {2020},
++  volume  = {145},
++  pages   = {113142},
++}
++
++@incollection{court1939hedonic,
++  author    = {Court, Andrew T.},
++  title     = {Hedonic price indexes with automotive examples},
++  booktitle = {The Dynamics of Automobile Demand},
++  publisher = {General Motors Corporation},
++  year      = {1939},
++  pages     = {99--117},
++}
++
++@article{cropper1988choice,
++  author  = {Cropper, Maureen L. and Deck, Leland B. and McConnell, Kenneth E.},
++  title   = {On the choice of functional form for hedonic price functions},
++  journal = {Review of Economics and Statistics},
++  year    = {1988},
++  volume  = {70},
++  number  = {4},
++  pages   = {668--675},
++}
++
++@article{ekeland2004identification,
++  author  = {Ekeland, Ivar and Heckman, James J. and Nesheim, Lars},
++  title   = {Identification and estimation of hedonic models},
++  journal = {Journal of Political Economy},
++  year    = {2004},
++  volume  = {112},
++  number  = {S1},
++  pages   = {S60--S109},
++}
++
++@article{goodman1998andrew,
++  author  = {Goodman, Allen C. and Thibodeau, Thomas G.},
++  title   = {Housing market segmentation},
++  journal = {Journal of Housing Economics},
++  year    = {1998},
++  volume  = {7},
++  number  = {2},
++  pages   = {121--143},
++}
++
++@incollection{griliches1961hedonic,
++  author    = {Griliches, Zvi},
++  title     = {Hedonic price indexes for automobiles: {A}n econometric analysis of quality change},
++  booktitle = {The Price Statistics of the Federal Government},
++  publisher = {NBER},
++  year      = {1961},
++  pages     = {173--196},
++}
++
++@article{halvorsen1981choice,
++  author  = {Halvorsen, Robert and Pollakowski, Henry O.},
++  title   = {Choice of functional form for hedonic price equations},
++  journal = {Journal of Urban Economics},
++  year    = {1981},
++  volume  = {10},
++  number  = {1},
++  pages   = {37--49},
++}
++
++@article{hill2013hedonic,
++  author  = {Hill, Robert J.},
++  title   = {Hedonic price indexes for residential housing: {A} survey, evaluation and taxonomy},
++  journal = {Journal of Economic Surveys},
++  year    = {2013},
++  volume  = {27},
++  number  = {5},
++  pages   = {879--914},
++}
++
++@inproceedings{ke2017lightgbm,
++  author    = {Ke, Guolin and Meng, Qi and Finley, Thomas and Wang, Taifeng and Chen, Wei and Ma, Weidong and Ye, Qiwei and Liu, Tie-Yan},
++  title     = {{LightGBM}: {A} highly efficient gradient boosting decision tree},
++  booktitle = {Advances in Neural Information Processing Systems},
++  year      = {2017},
++  pages     = {3146--3154},
++}
++
++@article{knight2002listing,
++  author  = {Knight, John R.},
++  title   = {Listing price, time on market, and ultimate selling price},
++  journal = {Real Estate Economics},
++  year    = {2002},
++  volume  = {30},
++  number  = {2},
++  pages   = {213--237},
++}
++
++@article{koenker1978regression,
++  author  = {Koenker, Roger and Bassett, Gilbert},
++  title   = {Regression quantiles},
++  journal = {Econometrica},
++  year    = {1978},
++  volume  = {46},
++  number  = {1},
++  pages   = {33--50},
++}
++
++@article{kok2017big,
++  author  = {Kok, Nils and Koponen, Eija-Leena and Mart{\'i}nez-Barbosa, Carmen A.},
++  title   = {Big data in real estate? {F}rom manual appraisal to automated valuation},
++  journal = {Journal of Portfolio Management},
++  year    = {2017},
++  volume  = {43},
++  number  = {6},
++  pages   = {202--211},
++}
++
++@article{lancaster1966new,
++  author  = {Lancaster, Kelvin J.},
++  title   = {A new approach to consumer theory},
++  journal = {Journal of Political Economy},
++  year    = {1966},
++  volume  = {74},
++  number  = {2},
++  pages   = {132--157},
++}
++
++@book{lesage2009introduction,
++  author    = {LeSage, James and Pace, R. Kelley},
++  title     = {Introduction to Spatial Econometrics},
++  publisher = {Chapman and Hall/CRC},
++  year      = {2009},
++}
++
++@article{liao2012hedonic,
++  author  = {Liao, Wen-Chi and Wang, Xizhu},
++  title   = {Hedonic house prices and spatial quantile regression},
++  journal = {Journal of Housing Economics},
++  year    = {2012},
++  volume  = {21},
++  number  = {1},
++  pages   = {16--27},
++}
++
++@inproceedings{lundberg2017unified,
++  author    = {Lundberg, Scott M. and Lee, Su-In},
++  title     = {A unified approach to interpreting model predictions},
++  booktitle = {Advances in Neural Information Processing Systems},
++  year      = {2017},
++  pages     = {4765--4774},
++}
++
++@article{lundberg2020local,
++  author  = {Lundberg, Scott M. and Erion, Gabriel and Chen, Hugh and DeGrave, Alex and Prutkin, Jordan M. and Nair, Bala and Katz, Ronit and Himmelfarb, Jonathan and Bansal, Nisha and Lee, Su-In},
++  title   = {From local explanations to global understanding with explainable {AI} for trees},
++  journal = {Nature Machine Intelligence},
++  year    = {2020},
++  volume  = {2},
++  number  = {1},
++  pages   = {56--67},
++}
++
++@article{mackinnon1985some,
++  author  = {MacKinnon, James G. and White, Halbert},
++  title   = {Some heteroskedasticity-consistent covariance matrix estimators with improved finite sample properties},
++  journal = {Journal of Econometrics},
++  year    = {1985},
++  volume  = {29},
++  number  = {3},
++  pages   = {305--325},
++}
++
++@article{mak2010quantile,
++  author  = {Mak, Stephen and Choy, Lennon and Ho, Winky},
++  title   = {Quantile regression estimates of {H}ong {K}ong real estate prices},
++  journal = {Urban Studies},
++  year    = {2010},
++  volume  = {47},
++  number  = {11},
++  pages   = {2461--2472},
++}
++
++@incollection{malpezzi2003hedonic,
++  author    = {Malpezzi, Stephen},
++  title     = {Hedonic pricing models: {A} selective and applied review},
++  booktitle = {Housing Economics and Public Policy},
++  editor    = {O'Sullivan, Tony and Gibb, Kenneth},
++  publisher = {Blackwell},
++  year      = {2003},
++  pages     = {67--89},
++}
++
++@article{meyer2019importance,
++  author  = {Meyer, Hanna and Pebesma, Edzer},
++  title   = {Predicting into unknown space? {E}stimating the area of applicability of spatial prediction models},
++  journal = {Methods in Ecology and Evolution},
++  year    = {2019},
++  volume  = {12},
++  number  = {9},
++  pages   = {1620--1633},
++}
++
++@article{mullainathan2017machine,
++  author  = {Mullainathan, Sendhil and Spiess, Jann},
++  title   = {Machine learning: {A}n applied econometric approach},
++  journal = {Journal of Economic Perspectives},
++  year    = {2017},
++  volume  = {31},
++  number  = {2},
++  pages   = {87--106},
++}
++
++@article{oates1969effects,
++  author  = {Oates, Wallace E.},
++  title   = {The effects of property taxes and local public spending on property values},
++  journal = {Journal of Political Economy},
++  year    = {1969},
++  volume  = {77},
++  number  = {6},
++  pages   = {957--971},
++}
++
++@incollection{roberts2013endogeneity,
++  author    = {Roberts, Michael R. and Whited, Toni M.},
++  title     = {Endogeneity in empirical corporate finance},
++  booktitle = {Handbook of the Economics of Finance},
++  editor    = {Constantinides, George M. and Harris, Milton and Stulz, Ren{\'e} M.},
++  publisher = {Elsevier},
++  year      = {2013},
++  volume    = {2A},
++  pages     = {493--572},
++}
++
++@article{roberts2017cross,
++  author  = {Roberts, David R. and Bahn, Volker and Ciuti, Simone and Boyce, Mark S. and Elith, Jane and Guillera-Arroita, Gurutzeta and Hauenstein, Severin and Lahoz-Monfort, Jos{\'e} J. and Schr{\"o}der, Boris and Thuiller, Wilfried and Warton, David I. and Wintle, Brendan A. and Hartig, Florian and Dormann, Carsten F.},
++  title   = {Cross-validation strategies for data with temporal and spatial dependence},
++  journal = {Ecography},
++  year    = {2017},
++  volume  = {40},
++  number  = {8},
++  pages   = {913--929},
++}
++
++@article{rosen1974hedonic,
++  author  = {Rosen, Sherwin},
++  title   = {Hedonic prices and implicit markets: {P}roduct differentiation in pure competition},
++  journal = {Journal of Political Economy},
++  year    = {1974},
++  volume  = {82},
++  number  = {1},
++  pages   = {34--55},
++}
++
++@incollection{shapley1953value,
++  author    = {Shapley, Lloyd S.},
++  title     = {A value for $n$-person games},
++  booktitle = {Contributions to the Theory of Games II},
++  editor    = {Kuhn, Harold W. and Tucker, Albert W.},
++  publisher = {Princeton University Press},
++  year      = {1953},
++  pages     = {307--317},
++}
++
++@article{sirmans2005composition,
++  author  = {Sirmans, Stacy and Macpherson, David and Zietz, Emily},
++  title   = {The composition of hedonic pricing models},
++  journal = {Journal of Real Estate Literature},
++  year    = {2005},
++  volume  = {13},
++  number  = {1},
++  pages   = {3--43},
++}
++
++@article{white1980heteroskedasticity,
++  author  = {White, Halbert},
++  title   = {A heteroskedasticity-consistent covariance matrix estimator and a direct test for heteroskedasticity},
++  journal = {Econometrica},
++  year    = {1980},
++  volume  = {48},
++  number  = {4},
++  pages   = {817--838},
++}
++
++@article{zietz2008determinants,
++  author  = {Zietz, Joachim and Zietz, Emily N. and Sirmans, G. Stacy},
++  title   = {Determinants of house prices: {A} quantile regression approach},
++  journal = {Journal of Real Estate Finance and Economics},
++  year    = {2008},
++  volume  = {37},
++  number  = {4},
++  pages   = {317--333},
++}

added paper/sections/conclusion.tex +21 −0

++% Author: Simon-Pierre Boucher — contact@spboucher.ai
++%
++% ═══════════════════════════════════════════════════════════════════════
++% 9. CONCLUSION
++% ═══════════════════════════════════════════════════════════════════════
++\section{Conclusion}
++\label{sec:conclusion}
++
++This paper has compared three approaches to hedonic housing price analysis---OLS, quantile regression, and gradient-boosted machine learning with SHAP interpretation---using a large Zillow listing sample of 788,842 U.S.\ properties. Each framework answers a different question, and the robustness extensions in this version document the boundaries of each framework's conclusions.
++
++OLS provides interpretable conditional mean associations: a price-to-area elasticity of 0.63, a 22.6\% bathroom listing-price gradient, a 33.4\% foreclosure discount, and regional listing-price differentials of 49\%--63\% between coastal and interior markets. The progression from region FE ($R^2 = 0.634$) to ZIP3 FE ($R^2 = 0.725$) demonstrates that fine-grained geographic controls capture substantial variation, but the imputation sensitivity analysis reveals that the lot-size gradient is attenuated threefold by state-median imputation.
++
++Quantile regression reveals that mean effects mask substantial distributional heterogeneity, now formally confirmed by inter-quantile Wald tests that reject coefficient equality for 11 of 13 variables. The garage listing-price gradient is ten times larger at the 10th percentile than the 90th ($z = 28.92$); the pool gradient is insignificant below the median but reaches 9.9\% at $\tau = 0.90$. Subsample stability analysis identifies age as the one coefficient that is genuinely unstable across geographic subsamples.
++
++XGBoost captures non-linearities and interactions that improve prediction from $R^2 = 0.630$ (OLS) to $R^2 = 0.833$ under random validation. However, this figure substantially overstates generalization ability. The ablation analysis reveals that neighborhood features drive the largest predictive gain ($+17.6$ pp) but that the full model with region dummies actively harms geographic holdout ($-7.6$ pp). The most striking result is that removing all geographic features \emph{improves} geographic holdout $R^2$ from 0.425 to 0.519, while adding latitude and longitude does the opposite ($+3.7$ pp random, $-5.5$ pp geographic). Geographic features help the model memorize location-specific prices but do not improve its ability to generalize attribute-price relationships to new markets.
++
++SHAP values identify the features that contribute most to predictions---living area, bathrooms, school quality, lot size, region---and this ranking is stable across three tree-based models (Spearman $\rho = 0.89$--$0.99$). But these remain predictive decompositions, not structural listing-price gradients. Moran's $I = 0.27$ on OLS residuals---stable across three subsamples (std $= 0.008$)---confirms that regional controls leave substantial spatial dependence unaddressed.
++
++The central contribution is methodological: we demonstrate that model evaluation depends critically on validation design. Random splits overstate generalization, geographic features can harm geographic holdout, SHAP values are stable across models but remain non-structural, and imputation can attenuate key coefficients. Future research should integrate spatial econometric methods, use transaction prices, employ geographic holdout validation as standard practice, incorporate climate risk data, and benchmark against generalized additive models to decompose the ML predictive gain into non-linearity versus spatial partitioning components.
++
++The central lesson is not that machine learning replaces hedonic econometrics, but that prediction, distributional heterogeneity, and economic interpretation answer different questions and should be combined carefully in modern housing valuation research.

added paper/sections/data.tex +192 −0

++% Author: Simon-Pierre Boucher — contact@spboucher.ai
++%
++% ═══════════════════════════════════════════════════════════════════════
++% 3. DATA
++% ═══════════════════════════════════════════════════════════════════════
++\section{Data and Variable Construction}
++\label{sec:data}
++
++\subsection{Data Source}
++
++The dataset is sourced from Zillow, the largest online real estate marketplace in the United States. The raw data contain 839,313 residential properties with 116 variables, representing active for-sale listings as of 2025--2026. The data include listing prices, structural characteristics, geocoordinates, neighborhood quality scores, and tax/transaction histories.
++
++\textbf{Important limitations of the data source.} The sample comprises active Zillow listings, not the universe of U.S.\ residential properties. Several sources of non-representativeness should be noted: (i) Zillow coverage varies by region, with some MLS-linked markets better represented than others; (ii) active listings capture supply at a point in time, not the full housing stock; (iii) the sample excludes off-market properties, FSBOs not listed on Zillow, and recently transacted properties that are no longer listed; (iv) Southern states are overrepresented (56.6\% of the sample vs.\ approximately 38\% of U.S.\ housing units), likely reflecting higher listing volumes in fast-growing Sun Belt markets. We do not claim national representativeness and caution against interpreting our estimates as population parameters for the entire U.S.\ housing market.
++
++\subsection{Listing Prices versus Transaction Prices}
++
++A critical limitation is that our dependent variable is the \textit{listing} (asking) price, not the realized transaction price. Listing prices reflect seller expectations and strategic pricing behavior, not necessarily market-clearing values. List-to-sale price ratios vary by market condition, property type, and price tier: luxury properties are more frequently overpriced, distressed properties may be strategically underpriced, and regional norms for overbidding versus negotiation differ substantially \citep{knight2002listing}. Throughout this paper, we interpret the estimated coefficients as \textbf{listing-price capitalization gradients}---conditional associations between attributes and asking prices---rather than transaction-price implicit prices. If listing premiums correlate systematically with property attributes (e.g., if waterfront properties are more frequently overpriced), the estimated gradients will reflect this pricing behavior in addition to underlying valuation differences.
++
++\subsection{Sample Construction}
++
++Table~\ref{tab:attrition} documents the sample construction.
++
++\begin{table}[H]
++\centering
++\caption{Sample Construction}
++\label{tab:attrition}
++\begin{threeparttable}
++\begin{tabular}{lrrr}
++\toprule
++Step & $N$ remaining & Removed & Criterion \\
++\midrule
++Raw Zillow records & 839,313 & --- & --- \\
++Valid price & 817,473 & 21,840 & $\$10{,}000 < P < \$10{,}000{,}000$ \\
++Valid living area & 797,380 & 20,093 & $200 < \text{sqft} < 20{,}000$ \\
++Valid bedrooms/bathrooms & 790,799 & 6,581 & $1 \leq \text{bed} \leq 10$, $1 \leq \text{bath} \leq 10$ \\
++Valid geocoordinates & 789,199 & 1,600 & Non-missing lat/lon \\
++U.S.\ states + DC only & 788,842 & 357 & Exclude PR, VI \\
++\midrule
++\textbf{Final analytical sample} & \textbf{788,842} & \textbf{50,471} & \textbf{(6.0\% removed)} \\
++\bottomrule
++\end{tabular}
++\begin{tablenotes}
++\small
++\item \textit{Notes:} Filters applied sequentially. The 6.0\% removal rate suggests the raw data are reasonably clean, though the retained sample may still contain measurement error in secondary variables.
++\end{tablenotes}
++\end{threeparttable}
++\end{table}
++
++\subsection{Variable Description}
++
++Our specification includes 62 regressors organized into six categories.
++
++\subsubsection{Structural Attributes (8 Variables)}
++
++The natural logarithm of living area ($\ln\text{sqft}$), number of bedrooms, number of bathrooms, property age ($2026 - \text{year\_built}$) and its square, number of stories, the bathroom-to-bedroom ratio, and square feet per bedroom. Living area enters in log form to accommodate the well-documented concavity of the size-price relationship.
++
++\subsubsection{Lot Characteristics (1 Variable)}
++
++The natural logarithm of lot size ($\ln\text{lot}$). Missing lot sizes (16.3\% of raw data) are imputed using state-level medians.
++
++\subsubsection{Amenity and Quality Indicators (11 Variables)}
++
++Binary indicators for swimming pool (39.8\% prevalence), spa (6.1\%), basement (24.3\%), fireplace (39.6\%), garage (67.2\%), waterfront location (8.9\%), central air conditioning (68.1\%), forced air heating (25.8\%), and hardwood flooring (26.7\%). The number of parking spaces and a composite luxury score (0--7) supplement these indicators.
++
++\subsubsection{Neighborhood and Location Variables (7 Variables)}
++
++Walk Score (0--100), Bike Score, Transit Score, average GreatSchools rating (1--10), school count, distance to nearest school, and local property tax rate.
++
++\textbf{Data quality note.} Bike Score has a maximum value of 248 in our data, exceeding the expected 0--100 range. Only 38 observations (0.005\%) exceed 100, and these are retained without truncation. Results are robust to capping Bike Score at 100.
++
++\subsubsection{Market Status Variables (5 Variables)}
++
++Condominium indicator (14.6\%), HOA membership (37.1\%), log annualized HOA fees ($\ln(1 + \text{HOA}_\text{annual})$), new construction (5.9\%), and foreclosure status (0.5\%).
++
++\subsubsection{Interaction Terms (6 Variables)}
++
++\begin{itemize}[nosep]
++    \item $\ln(\text{sqft}) \times \text{age}$: depreciation-size interaction;
++    \item $\text{pool} \times \text{South}$: climate-dependent pool gradient;
++    \item $\text{waterfront} \times \ln(\text{sqft})$: size-dependent waterfront gradient;
++    \item $\text{basement} \times \text{North}$: region-dependent basement gradient;
++    \item $\text{condo} \times \text{walk\_score}$: walkability gradient for condominiums;
++    \item $\text{age} \times \text{luxury\_score}$: luxury mitigation of depreciation.
++\end{itemize}
++
++\subsubsection{Categorical Controls (24 Dummy Variables)}
++
++Simplified indicators for roof type (6 dummies), construction material (8 dummies), foundation type (7 dummies), and Census region (3 dummies; Midwest reference).
++
++\subsection{Missing Data and Imputation}
++
++Table~\ref{tab:missing} reports missingness rates for key variables.
++
++\begin{table}[H]
++\centering
++\caption{Missing Data Rates and Imputation Methods}
++\label{tab:missing}
++\begin{threeparttable}
++\small
++\begin{tabular}{lrrl}
++\toprule
++Variable & Missing (\%) & Method & Notes \\
++\midrule
++Year built & 19.4 & State median & Affects age, age$^2$, interactions \\
++Lot size & 16.3 & State median & Large variation \\
++Walk Score & 3.1 & State median & \\
++Bike Score & 6.1 & State median & Max = 248 (38 obs.) \\
++Transit Score & 70.1 & Set to 0 & Suburban/rural properties \\
++Garage & 35.1 & Set to False & Conservative \\
++Climate risk factors & 100.0 & Excluded & Not available \\
++\bottomrule
++\end{tabular}
++\begin{tablenotes}
++\small
++\item \textit{Notes:} State-level median imputation is used to preserve geographic variation. The high Transit Score missingness (70.1\%) likely reflects properties in areas without public transit infrastructure, for which zero is a reasonable value. Climate risk factors (flood, fire, heat, wind, air) are entirely missing and excluded from the analysis.
++\end{tablenotes}
++\end{threeparttable}
++\end{table}
++
++\subsection{Data Quality Audit}
++\label{sec:data_audit}
++
++We conduct three data quality checks to assess the sensitivity of key results to imputation and outliers.
++
++\textbf{Imputation prevalence.} Two variables---year built (19.4\% missing) and lot size (16.3\% missing)---account for the bulk of imputed values. To assess the consequences, we re-estimate the baseline OLS model on subsamples that exclude imputed observations (Section~\ref{sec:imputation_sensitivity}). The lot-size coefficient is the most sensitive: $\ln(\text{lot})$ triples from 0.018 to 0.059 when imputed lot sizes are dropped, suggesting that state-median imputation attenuates the lot-size gradient substantially.
++
++\textbf{Outlier prevalence.} We winsorize lot size at its 99.5th percentile and cap Bike Score at 100, then re-estimate OLS (Section~\ref{sec:winsorization}). The overall $R^2$ increases modestly from 0.634 to 0.640, and most coefficients are stable, with the exception of $\ln(\text{lot})$, which again increases substantially.
++
++\textbf{Geographic coverage.} The sample spans 886 unique three-digit ZIP code prefixes (ZIP3 codes) across 51 jurisdictions (50 states plus DC). Southern states account for 56.6\% of observations. We document the marginal explanatory power of progressively finer geographic controls in Section~\ref{sec:ols_fe}.
++
++\subsection{Descriptive Statistics}
++
++Table~\ref{tab:descriptive} presents summary statistics.
++
++\begin{table}[H]
++\centering
++\caption{Descriptive Statistics ($N = 788{,}842$)}
++\label{tab:descriptive}
++\begin{threeparttable}
++\small
++\begin{tabular}{lrrrrrr}
++\toprule
++Variable & Mean & Std.\ Dev. & Min & Median & Max \\
++\midrule
++\multicolumn{6}{l}{\textit{Continuous Variables}} \\
++Listing Price (\$) & 621,737 & 817,965 & 10,300 & 399,900 & 9,999,999 \\
++Living Area (sqft) & 2,093 & 1,181 & 208 & 1,820 & 19,600 \\
++Bedrooms & 3.25 & 1.09 & 1 & 3 & 10 \\
++Bathrooms & 2.52 & 1.16 & 1 & 2 & 10 \\
++Property Age (years) & 42.2 & 31.5 & 0 & 36 & 200 \\
++Walk Score (0--100) & 25.6 & 26.5 & 0 & 16 & 100 \\
++Bike Score & 34.9 & 18.1 & 1 & 31 & 248 \\
++Transit Score (0--100) & 8.9 & 18.3 & 0 & 0 & 100 \\
++Avg.\ School Rating (1--10) & 6.02 & 0.90 & 1 & 6 & 10 \\
++Property Tax Rate (\%) & 1.10 & 0.53 & 0 & 1.0 & 4.0 \\
++Luxury Score (0--7) & 1.36 & 1.29 & 0 & 1 & 7 \\
++\midrule
++\multicolumn{6}{l}{\textit{Binary Variables (prevalence)}} \\
++Swimming Pool & 39.8\% & & & & \\
++Garage & 67.2\% & & & & \\
++Fireplace & 39.6\% & & & & \\
++Basement & 24.3\% & & & & \\
++Waterfront & 8.9\% & & & & \\
++HOA & 37.1\% & & & & \\
++Central Air & 68.1\% & & & & \\
++Hardwood Floors & 26.7\% & & & & \\
++Condominium & 14.6\% & & & & \\
++New Construction & 5.9\% & & & & \\
++Foreclosure & 0.5\% & & & & \\
++\midrule
++\multicolumn{6}{l}{\textit{Regional Distribution}} \\
++South & 56.6\% & & & & \\
++West & 18.9\% & & & & \\
++Midwest & 16.1\% & & & & \\
++Northeast & 8.4\% & & & & \\
++\bottomrule
++\end{tabular}
++\begin{tablenotes}
++\small
++\item \textit{Notes:} Listing prices, not transaction prices. Property age computed as $2026 - \text{year\_built}$, after imputation. Imputed values included in summary statistics.
++\end{tablenotes}
++\end{threeparttable}
++\end{table}
++
++The median listing price is \$399,900, with substantial right-skewness (mean \$621,737). The log transformation substantially improves distributional symmetry (Figure~\ref{fig:price_dist}), supporting the semi-log specification.
++
++\begin{figure}[H]
++    \centering
++    \includegraphics[width=\textwidth]{figures/fig1_price_distribution.png}
++    \caption{Distribution of Listing Prices: (a) Levels; (b) Natural Logarithm. The log transformation reduces right skewness and approximates normality.}
++    \label{fig:price_dist}
++\end{figure}

added paper/sections/discussion.tex +46 −0

Large diff (46 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/introduction.tex +33 −0

Large diff (33 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/limitations.tex +39 −0

Large diff (39 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/literature.tex +39 −0

Large diff (39 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/methodology.tex +130 −0

Large diff (130 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/results.tex +590 −0

Large diff (590 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/robustness.tex +164 −0

Large diff (164 lines) is not loaded by default to keep the page fast.Load diff

added paper/sections/titlepage.tex +80 −0

Large diff (80 lines) is not loaded by default to keep the page fast.Load diff

added paper/uq_logo.jpg +0 −0

Binary file not shown.

added requirements.txt +15 −0

Large diff (15 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/imputation_sensitivity.csv +5 −0

Large diff (5 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/iqr_wald_tests.csv +14 −0

Large diff (14 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/morans_i_robustness.csv +4 −0

Large diff (4 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/ols_standardized.csv +64 −0

Large diff (64 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/ols_unstandardized.csv +64 −0

Large diff (64 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/qr_coefficients.csv +64 −0

Large diff (64 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/qr_pseudo_r2.csv +2 −0

Large diff (2 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/qr_stability.csv +14 −0

Large diff (14 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/shap_cross_model_stability.csv +4 −0

Large diff (4 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/shap_importance_xgb.csv +63 −0

Large diff (63 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/winsorization_sensitivity.csv +13 −0

Large diff (13 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/xgb_geography_and_ablation.csv +9 −0

Large diff (9 lines) is not loaded by default to keep the page fast.Load diff

added results/tables/zip3_fixed_effects.csv +6 −0

Large diff (6 lines) is not loaded by default to keep the page fast.Load diff

added scripts/01_spatial_robustness.py +167 −0

Large diff (167 lines) is not loaded by default to keep the page fast.Load diff

added scripts/02_qr_imputation.py +210 −0

Large diff (210 lines) is not loaded by default to keep the page fast.Load diff

added scripts/03_make_figures.py +426 −0

Large diff (426 lines) is not loaded by default to keep the page fast.Load diff

added scripts/04_export_tables.py +135 −0

Large diff (135 lines) is not loaded by default to keep the page fast.Load diff

added src/wp3/__init__.py +3 −0

Large diff (3 lines) is not loaded by default to keep the page fast.Load diff

added src/wp3/config.py +54 −0

Large diff (54 lines) is not loaded by default to keep the page fast.Load diff

added src/wp3/data.py +58 −0

Large diff (58 lines) is not loaded by default to keep the page fast.Load diff

added src/wp3/models.py +62 −0

Large diff (62 lines) is not loaded by default to keep the page fast.Load diff

added src/wp3/plotting.py +112 −0

Large diff (113 lines) is not loaded by default to keep the page fast.Load diff

spb/wp3_uqo

Initial commit: WP3 research compendium (hedonic housing prices, US)

Theme