/**
 * =============================================================================
 * QWHPI — Quebec Weekly Housing Price Index
 * Author  : Simon-Pierre Boucher
 * Contact : contact@spboucher.ai
 * File    : web/app/methodology/page.tsx
 * Purpose : Methodology — rendered summary of the v2.1 monthly robust index.
 * =============================================================================
 */

export default function Methodology() {
  return (
    <>
      <h1>Methodology (v2.1 — monthly, robust)</h1>
      <p className="lede">
        QHPI measures price movement, never composition movement. Version 2
        rebuilt the index at monthly frequency around the rolling-time-dummy
        method used by official statistical agencies.
      </p>

      <h2>Data</h2>
      <p>
        ~745,000 residential transactions across 1,100+ Quebec municipalities,
        January 2021 to present, spatially joined to the official SDA
        1/20&nbsp;000 boundaries. Non-arm&apos;s-length transfers, duplicates
        and portfolio-scale conveyances are excluded with a documented
        exclusion table (~3.5%). The <em>indéterminé</em> type never enters an
        index. <strong>Variables whose missingness moves over time are banned
        from the model</strong>: the provider backfilled
        <code>buildingType</code> in region-staggered waves (2022–2023), which
        would fabricate artificial index steps — it was detected by a
        composition-free arbitration and excluded; building age uses
        time-invariant conditional-median imputation.
      </p>

      <h2>Three estimators, one family</h2>
      <ul>
        <li>
          <strong>Province × type — rolling-time-dummy (RTD).</strong>{" "}
          13-month hedonic windows re-estimated every month with Huber-robust
          weighting (outliers are downweighted inside the regression), linked
          by the <em>mean splice</em>. Published history never revises, and
          hedonic coefficients are free to drift (β on log floor area moves
          ~5% across windows).
        </li>
        <li>
          <strong>Liquid cells (≥ 40 tx/month) — direct local estimation.</strong>{" "}
          Own robust time-dummy regression (own coefficients, own postal-zone
          fixed effects) with a light state-space smoother for the real-time
          variant. Chosen because deviation-from-pooled-surface methods
          compress strong local divergences: Québec City condos appreciated
          ~+55% by repeat sales AND stratified matched-cell medians, which the
          direct estimator reproduces (+53–64%) while pooled deviations said
          +42%.
        </li>
        <li>
          <strong>Thin cells — hierarchical shrinkage.</strong> Monthly mean
          deviations from the parent path filtered by a heteroskedastic
          local-level Kalman model: liquid months speak, thin months shrink
          toward the parent.
        </li>
      </ul>

      <h2>Validation</h2>
      <ul>
        <li>
          <strong>Repeat sales (BMN)</strong>: published levels agree within
          ±5% on six of seven benchmark cells, with high change-correlations at
          the province level. The exception (Montréal single-family, −8%) sits
          between repeat sales and the stratified matched-cell median.
        </li>
        <li>
          <strong>Stratified matched-cell medians</strong> (FSA × vintage ×
          size, regression-free) corroborate the direct estimator on every
          arbitrated cell.
        </li>
        <li>
          <strong>Downsampling</strong>: direct-estimation RMSE stays ≈1.9% at
          40 tx/month (the liquidity floor); hierarchical shrinkage takes over
          below.
        </li>
        <li>
          <strong>Composition shock</strong>: removing 70% of small-dwelling
          sales moves the raw median +12.3% but the index only −1.0%.
        </li>
        <li>
          <strong>Seasonality</strong>: no stable monthly seasonality — all
          series are NSA.
        </li>
      </ul>

      <h2>Reliability grades</h2>
      <table className="data">
        <thead>
          <tr><th>Grade</th><th>Meaning</th><th>Liquidity</th></tr>
        </thead>
        <tbody>
          <tr><td>A</td><td>Very strong; direct estimation, tight CI</td><td>≥ 150 tx/month</td></tr>
          <tr><td>B</td><td>Strong; direct estimation</td><td>75–149</td></tr>
          <tr><td>C</td><td>Moderate; direct estimation floor</td><td>40–74</td></tr>
          <tr><td>D</td><td>Thin; hierarchical shrinkage</td><td>15–39</td></tr>
          <tr><td>E</td><td>Model-implied only</td><td>&lt; 15</td></tr>
        </tbody>
      </table>

      <h2>Conventions</h2>
      <p>
        Base 2021 average = 100. Continuous monthly grid; the trailing month is
        flagged <code>is_partial_month</code> while registrations arrive. Every
        observation ships with a 95% interval, transaction count, effective
        sample size and shrinkage weight. First releases are preserved and
        revisions are queryable (<code>/v1/vintages</code>). Growth horizons:
        1m, 3m, 6m, YoY.
      </p>

      <p className="note">
        Author: Simon-Pierre Boucher — contact@spboucher.ai · Key references:
        Hill, Scholz, Shimizu &amp; Steurer (2022) J. Official Statistics;
        Eurostat/IMF/OECD RPPI Handbook (2013); Bailey, Muth &amp; Nourse
        (1963); Case &amp; Shiller (1989).
      </p>
    </>
  );
}