# Méthodologie — Modèle hédonique de prix des maisons (Québec)

Pipeline : Realtor.ca + DuProprio → nettoyage → feature engineering (règles + LLM + vision) → régression hédonique log-linéaire à effets fixes.

# 1. Origine des données

• Collecte : scrapers Apify, extraction le 2026-07-03. Chaque enregistrement est un objet JSON structuré.
• Champs communs : source, url, listingId, title, price/priceNumber, currency, address{full,street,city,province,postalCode,...}, property{...}, features[], description, images[], scrapedAt.
• Spécificités :
  • Realtor : property.buildingType, storeys, yearBuilt, parkingSpaces, rooms[] (dimensions par pièce), pas de coordonnées GPS, images sans caption utile.
  • DuProprio : property.type, levels, coordinates{lat,lon} (7 691 présentes), images avec captions (Kitchen, etc.), pas de rooms.
• Instantané transversal (cross-section) : un seul point dans le temps → pas de dimension temporelle, donc pas d'effet fixe temporel nécessaire.

Identifiant unique construit : uid = source + ":" + listingId (évite toute collision entre les deux espaces d'ID).

# 2. Construction du dataset combiné « maisons »

1. Fusion des deux tableaux JSON (schéma harmonisé).
2. Définition de « maison » (choix utilisateur : unifamiliales + townhouses) :
   • Realtor : buildingType ∈ {House, Row / Townhouse}
   • DuProprio : type ∈ {Home, Bungalow, Semi Detached, Intergenerational, Country Home, Cottage, Villa, Townhouse}
   • Exclus : condos, plex (duplex→quintuplex), terrains/lots, fermes, commercial, mobile homes.
3. Filtre prix présent : priceNumber non nul et > 0.

→ 19 273 maisons avec prix (15 470 Realtor + 3 803 DuProprio).

# 3. Nettoyage des aberrations

Les prix scrappés contiennent des erreurs de parsing (min 899 $, max 368 G$). Règles appliquées :

→ 19 115 maisons conservées (158 retirées).

Principe : on borne plutôt que de supprimer quand une seule variable est aberrante (on met la variable à manquant et on l'impute), pour ne pas perdre l'observation entière.

# 4. Construction des variables

# 4.1 Variable cible

ln_price = ln(priceNumber) — transformation logarithmique (rend la distribution symétrique, linéarise les effets multiplicatifs, coefficients ≈ % d'impact sur le prix).

# 4.2 Variables structurelles (règles déterministes)

• Surface & terrain : parsing d'unités hétérogènes → tout en pieds carrés.
  • "1535 sqft", "1,333.2 ft²", "11 561.52 ft²" (séparateurs de milliers variés), "961.6 m2" (m² × 10,7639).
• Reconstruction de surface via les pièces (Realtor) : dimensions "23 ft ,4 in x 13 ft ,8 in" → pieds-décimaux → aire ; somme sur toutes les pièces. Calibration sur le recouvrement (ratio médian surface réelle / somme pièces ≈ 0,98) → sert à combler squareFeet manquant.
  • Constat : les annonces à pièces détaillées ≈ celles qui ont déjà squareFeet → gain de couverture faible, mais les comptes/types de pièces restent informatifs.
• Autres : beds, baths, parking (Realtor), storeys/levels, age = 2026 − yearBuilt (+ age² pour la courbure), drapeaux has_* marquant les valeurs imputées.

# 4.3 Aménités (règles par mots-clés bilingues)

17 dummies détectés dans features[] + description + title (FR/EN) : piscine, bord de l'eau, garage, foyer, climatisation/thermopompe, sous-sol fini, cul-de-sac, golf, ski, proximité parc/école/autoroute/transport, absence de voisin arrière.

# 4.4 Détail des pièces (Realtor, rooms[])

Nombre de pièces, nombre de niveaux, chambre principale, sous-sol, bureau, salle familiale, atelier, cellier à vin, solarium, mezzanine, bibliothèque, buanderie.

# 4.5 Signaux de listing

Nombre de photos (n_images, écrêté à 60), présence de visite virtuelle — proxies de gamme/qualité de la mise en marché.

# 4.6 Variables géographiques (effets fixes)

• Ville nettoyée (Realtor : on retire le quartier entre parenthèses ; minuscules ; normalisation). Villes avec ≥ 20 annonces → dummy propre ; les rares → __other__. ≈ 194 villes en effets fixes.
• Type de propriété harmonisé, regroupé si < 30 annonces.
• Source (Realtor/DuProprio) → dummy captant les différences systématiques entre plateformes.

# 4.7 Imputation

Valeurs manquantes après nettoyage : imputées par médiane par type de propriété (puis médiane globale), avec un drapeau has_* pour que le modèle distingue « valeur observée » de « valeur imputée ».

# 5. Mécanismes IA pour le feature engineering

Deux couches IA extraient des variables impossibles à obtenir par règles — l'une du texte, l'autre des images.

# 5.1 Extraction de specs depuis la description — GPT-4o-mini (OpenAI)

• But : transformer la description libre en 20 attributs structurés (état : à rénover→neuf, clé en main, cuisine/sdb rénovée, revêtements de sol, comptoirs quartz/granit, chauffage, vue sur l'eau, revenus locatifs, grand terrain, secteur tranquille, + mots-clés de vente).
• Mécanisme : appel Chat Completions avec response_format = json_schema strict (schéma imposé, énumérations fermées) → sortie JSON valide garantie, pas de parsing fragile. temperature = 0 (déterminisme). Système : « extracteur factuel, uniquement d'après le texte ; absence → false/inconnu/[] ».
• Ingénierie : ~600 tokens in / ~110 out par annonce ; parallèle (24 threads), résumable (cache specs.jsonl clé = uid), retry exponentiel sur 429/5xx.
• Coût/temps : ~$3 / ~19 k annonces.

# 5.2 Attributs visuels de façade — Claude Haiku 4.5 (Anthropic, vision)

• But : lire ce que le texte ne dit pas — état visuel réel, attrait extérieur (curb appeal), niveau de rénovation, matériaux, aménagement paysager, cadre (urbain/banlieue/rural/bord d'eau/boisé), indice de luxe, qualité de la photo.
• Sélection d'image : 1 photo/annonce = la façade. Realtor → 1re photo. DuProprio → photo dont la caption est l'adresse (pas une pièce), via exclusion de mots-clés de pièces.
• Mécanisme : Messages API, image passée par URL (source.type = url, pas de téléchargement), output_config.format = json_schema (12 attributs, énumérations fermées). Système : « évaluateur objectif ; scores fondés sur critères concrets (surfaces, matériaux, aménagement), pas sur un goût personnel ; si non-extérieur → is_exterior=false ».
• Ingénierie : ~2 470 tokens in / ~100 out par image ; parallèle (16 threads), résumable (cache facade_specs.jsonl), retry sur 429/5xx/529.
• Coût/temps : ~$57 / ~19 k images.
• Pourquoi Haiku : modèle vision le moins cher et rapide, largement suffisant pour de la classification d'attributs concrets.

# 5.3 Pourquoi le JSON structuré strict est central

Le schéma imposé (types + enum + champs requis + additionalProperties:false) fait valider la sortie au niveau de l'API : le modèle est forcé de renvoyer exactement les champs attendus, dans le bon domaine de valeurs. On obtient des variables directement tabulables, reproductibles, sans post-traitement de texte libre.

# 5.4 Intégration au dataset

Les sorties LLM (clé uid) sont converties en variables numériques : booléens → 0/1, condition → score ordinal 0-5, revêtements → dummies (bois franc, quartz/granit), vue → dummy eau, etc., avec un drapeau has_gpt / is_exterior pour marquer la disponibilité.

# 6. Modèle économétrique

# 6.1 Spécification — hédonique log-linéaire à effets fixes

$$\ln(P_i) = \alpha + \beta,\ln(\text{surface}_i) + \gamma,\ln(\text{terrain}i) + \sum_k \delta_k X{ki} + \sum_c \lambda_c \mathbb{1}[\text{ville}_i=c] + \varepsilon_i$$

• Log-log sur surface et terrain → coefficients = élasticités (% prix par % surface).
• Log-niveau sur le reste → un coefficient $b$ ≈ $(e^b-1)\times100$ % d'impact sur le prix.
• Effets fixes ville ($\lambda_c$) : absorbent tout le différentiel de localisation (le plus gros déterminant du prix). Chaque coefficient = prime/décote de la ville vs la ville de référence.
• Effets fixes type de propriété et source.

# 6.2 Double spécification (couverture vs richesse)

Realtor ne rapporte squareFeet que pour ~38 % des annonces → deux modèles, prédictions combinées :

• Modèle A (riche) : inclut ln(surface), estimé sur les biens à surface mesurée (réelle ou reconstruite via pièces). Meilleur ajustement.
• Modèle B (large) : sans surface, estimé sur toutes les maisons → sert à pricer celles sans surface (via beds/baths/terrain/pièces + specs).
• Prédiction finale : A si surface mesurée, sinon B.

# 6.3 Estimation & inférence

• MCO (OLS) sur ln_price.
• Erreurs-types robustes à l'hétéroscédasticité HC3 (les résidus immobiliers sont hétéroscédastiques ; HC3 est conservateur en petit/moyen échantillon).
• Correction du biais de rétrotransformation : $\hat{P} = e^{\hat{\ln P}} \times e^{\hat\sigma^2/2}$ (correction normale de Duan) — sinon $e^{\hat{\ln P}}$ sous-estime systématiquement le niveau.

# 6.4 Interprétation

Coefficients rapportés en % d'impact prix + significativité (p-values sur SE HC3). Effets fixes ville présentés comme primes de localisation.

# 7. Statistiques & diagnostics

Progression observée : v2 (structurel) R²≈0,70 → v3 (+ pièces/photos) R²≈0,72 → v4 (+ specs GPT) → v5 (+ vision) attendu.

# 8. Limites & biais (transparence)

• Endogénéité / non-causalité : de belles photos ou des specs riches corrèlent avec des courtiers haut de gamme et des biens chers → coefficients prédictifs, pas causaux. À ne pas lire comme « ajouter une piscine ⇒ +X % ».
• Biais de sélection : uniquement des biens en vente (prix demandé, pas prix de transaction) ; les biens sans surface/pièces sont non aléatoires (annonces moins complètes).
• Imputation : les médianes par type réduisent la variance des variables imputées (atténuation possible des coefficients) — d'où les drapeaux has_*.
• Extraction LLM : erreurs/hallucinations possibles ; temperature=0 + schéma strict + énumérations fermées les limitent, mais pas de validation humaine systématique. La vision juge sur une seule photo.
• Instantané unique : pas de dynamique de marché ; primes de localisation figées au 2026-07-03.
• Couverture géographique : villes < 20 annonces regroupées en __other__ (moins de finesse spatiale là où les données sont rares).

# 9. Fichiers produits