Refresh v11-era borough/tier tables to v22 canonical; regenerate scatter data

Borough and price-tier tables across paper/technical report/demo script
carried v11 evaluation numbers (Manhattan 36.66%, tier 40.26%, etc.) and
technical_report had literal 0.xxxx R² placeholders. Update all to the
canonical segment metrics in models/meta.json; drop per-borough R²
columns (never computed for v22 — the training script only records
MedAPE/MAE per segment) and label the Staten Island paradox R² figures
as the v11 evaluation, noting the pattern persists in v22. Align
thesis_metrics.txt tier table with meta.json. Regenerate scatter_nyc/
riyadh.json from the v22/v12 stacks (was v21) and add per-borough/tier
diagnostics to generate_scatter.py. Regenerate .docx files.

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

data/processed/thesis_metrics.txt

@@ -28,10 +28,10 @@ building                   18.61%   0.5364      139
 ### Table 4: NYC — MedAPE by Price Tier ###
 Tier                 MedAPE        MAE ($)        N
 ----------------------------------------------------
-<$500K               27.17%        227,062    6,497
-$500K–1M             14.78%        179,839   10,980
-$1M–3M               21.30%        450,354    7,978
-$3M–10M              39.24%      2,160,740    1,707
+<$500K               27.10%        225,470    6,497
+$500K–1M             15.12%        182,149   10,980
+$1M–3M               21.30%        454,712    7,978
+$3M–10M              39.77%      2,180,172    1,707
 
 ### Table 5: NYC Stack — Per-Model Contributions (v22) ###
 Learner            R² Holdout     MedAPE

docs/demo_script.md

@@ -125,9 +125,9 @@ Riyadh click target:  24.6877,  46.7219   (Downtown Riyadh / King Fahd Road)
 **English:**
 > "Finally, the analytics dashboard. This shows model performance broken down by NYC borough and price tier."
 
-> "Notice the Staten Island paradox: lowest R² in the dataset — 0.41 — but the best MedAPE at 13.5%. That's because Staten Island has very low price variance; the model's absolute errors are small, but R² penalises a low-variance target. MedAPE is the right metric for a user-facing AVM."
+> "Notice the Staten Island paradox: the worst per-borough R² but the best MedAPE at 14.4%. That's because Staten Island has very low price variance; the model's absolute errors are small, but R² penalises a low-variance target. MedAPE is the right metric for a user-facing AVM."
 
-> "Manhattan is the hardest market at 36.7% MedAPE. Co-op board approval discounts and unobservable interior finishes create heterogeneity that no tabular dataset can capture."
+> "Manhattan is the hardest market at 35.2% MedAPE. Co-op board approval discounts and unobservable interior finishes create heterogeneity that no tabular dataset can capture."
 
 **Arabic:**
 > "لوحة التحليلات تُظهر أداء النموذج مقسّماً حسب منطقة نيويورك وشريحة السعر."

docs/demo_script.tex

@@ -329,12 +329,12 @@ consistent with documented Saudi negotiation margins of 20 to 50 percent.''
 ``Finally, the analytics dashboard. This shows model performance broken down by
 NYC borough and price tier.''
 
-``Notice the Staten Island paradox: lowest $R^2$ in the dataset --- 0.41 ---
-but the best MedAPE at 13.5\%. That's because Staten Island has very low price
+``Notice the Staten Island paradox: the worst per-borough $R^2$ but the best
+MedAPE at 14.4\%. That's because Staten Island has very low price
 variance; the model's absolute errors are small, but $R^2$ penalises a
 low-variance target. MedAPE is the right metric for a user-facing AVM.''
 
-``Manhattan is the hardest market at 36.7\% MedAPE. Co-op board approval
+``Manhattan is the hardest market at 35.2\% MedAPE. Co-op board approval
 discounts and unobservable interior finishes create heterogeneity that no
 tabular dataset can capture.''
 \end{narration}

docs/generate_docx.py

@@ -361,13 +361,13 @@ def build_paper(path):
     set_heading(doc, "7.2 Performance by Borough", level=2)
     add_table_style(
         doc,
-        headers=["Borough", "n", "R²", "MedAPE", "MAE"],
+        headers=["Borough", "n", "MedAPE", "MAE"],
         rows=[
-            ("Staten Island", "3,052", "0.4103", "13.46%", "$221,158"),
-            ("Queens",        "9,533", "0.6851", "17.06%", "$363,990"),
-            ("Bronx",         "2,735", "0.6195", "20.93%", "$1,517,641"),
-            ("Brooklyn",      "7,032", "0.6206", "20.89%", "$871,097"),
-            ("Manhattan",     "5,411", "0.6141", "36.66%", "$2,801,602"),
+            ("Staten Island", "3,052", "14.41%", "$220,216"),
+            ("Queens",        "9,533", "17.43%", "$366,226"),
+            ("Bronx",         "2,735", "21.08%", "$1,531,532"),
+            ("Brooklyn",      "7,032", "20.64%", "$857,322"),
+            ("Manhattan",     "5,411", "35.16%", "$2,714,327"),
         ],
         caption="Borough-level holdout performance",
     )
@@ -716,13 +716,13 @@ def build_technical_report(path):
     )
     add_table_style(
         doc,
-        headers=["Borough", "n", "R²", "MedAPE"],
+        headers=["Borough", "n", "MedAPE", "MAE"],
         rows=[
-            ("Staten Island", "3,052", "0.4103", "13.46%"),
-            ("Queens",        "9,533", "0.6851", "17.06%"),
-            ("Bronx",         "2,735", "0.6195", "20.93%"),
-            ("Brooklyn",      "7,032", "0.6206", "20.89%"),
-            ("Manhattan",     "5,411", "0.6141", "36.66%"),
+            ("Staten Island", "3,052", "14.41%", "$220,216"),
+            ("Queens",        "9,533", "17.43%", "$366,226"),
+            ("Bronx",         "2,735", "21.08%", "$1,531,532"),
+            ("Brooklyn",      "7,032", "20.64%", "$857,322"),
+            ("Manhattan",     "5,411", "35.16%", "$2,714,327"),
         ],
         caption="Borough-level performance",
     )
@@ -1136,10 +1136,10 @@ def build_demo_script(path):
          [
              ("English",
               "\"The analytics dashboard shows model performance broken down by NYC borough and price tier.\"\n\n"
-              "\"Notice the Staten Island paradox: lowest R²=0.41 but best MedAPE=13.5%. Staten Island has very "
+              "\"Notice the Staten Island paradox: the worst per-borough R² but the best MedAPE (14.4%). Staten Island has very "
               "low price variance; the model's absolute errors are small, but R² penalises a low-variance target. "
               "MedAPE is the right metric for a user-facing AVM.\"\n\n"
-              "\"Manhattan is hardest at 36.7% MedAPE. Co-op board approval discounts and unobservable interior "
+              "\"Manhattan is hardest at 35.2% MedAPE. Co-op board approval discounts and unobservable interior "
               "finishes create heterogeneity that no tabular dataset can capture.\""),
              ("Arabic",
               "\"لوحة التحليلات تُظهر أداء النموذج مقسّماً حسب منطقة نيويورك وشريحة السعر.\"\n\n"

docs/technical_report.tex

@@ -457,15 +457,15 @@ Separate XGBoost trained on Manhattan sales $\geq \$2{,}500{,}000$ ($n
 \begin{table}[H]
   \centering
   \caption{Borough-level holdout performance}
-  \begin{tabular}{lrrrr}
+  \begin{tabular}{lrrr}
     \toprule
-    Borough & $n$ & $R^2$ & MedAPE & MAE (USD) \\
+    Borough & $n$ & MedAPE & MAE (USD) \\
     \midrule
-    Manhattan     & 5,411 & 0.xxxx & 35.16\% & \$2,714,327 \\
-    Bronx         & 2,735 & 0.xxxx & 21.08\% & \$1,531,532 \\
-    Brooklyn      & 7,032 & 0.xxxx & 20.64\% &   \$857,322 \\
-    Queens        & 9,533 & 0.xxxx & 17.43\% &   \$366,226 \\
-    Staten Island & 3,052 & 0.xxxx & 14.41\% &   \$220,216 \\
+    Manhattan     & 5,411 & 35.16\% & \$2,714,327 \\
+    Bronx         & 2,735 & 21.08\% & \$1,531,532 \\
+    Brooklyn      & 7,032 & 20.64\% &   \$857,322 \\
+    Queens        & 9,533 & 17.43\% &   \$366,226 \\
+    Staten Island & 3,052 & 14.41\% &   \$220,216 \\
     \bottomrule
   \end{tabular}
 \end{table}

docs/technical_report.txt

@@ -537,26 +537,27 @@ LightGBM (wide)         0.6403    (not stored)   20.28%
 CatBoost (high-cap)     0.6426    (not stored)   20.35%
 Stack v22 (Ridge meta)  0.6495    $1,047,004     20.32%
 
-Improvement vs. baseline (linear regression on 3 features): R² 0.238 → 0.645
+Improvement vs. baseline (linear regression on 3 features): R² 0.238 → 0.6495
 Improvement vs. v1 (single XGBoost, 2022):                  MedAPE ~32% → 20.32%
 
 6.2 Performance by Borough (Holdout)
 ──────────────────────────────────────
 
-Borough           n         R²        MedAPE     MAE (USD)
-──────────────    ────────  ────────  ─────────  ──────────────
-Manhattan         5,411     0.xxxx    36.89%     $2,801,602
-Bronx             2,735     0.xxxx    21.05%     $1,517,641
-Brooklyn          7,032     0.xxxx    20.84%     $871,097
-Queens            9,533     0.xxxx    17.04%     $363,990
-Staten Island     3,052     0.xxxx    13.56%     $221,158
-
-Key finding — Staten Island paradox: lowest R² of any borough, yet best MedAPE
-at 13.56%. Explanation: Staten Island has very low price variance (most sales
-$300K–$700K). The model predicts well in absolute terms, but R² penalises a
-low-variance target disproportionately. MedAPE is the user-relevant metric.
-
-Manhattan is hardest: 36.89% MedAPE. Reasons:
+Borough           n         MedAPE     MAE (USD)
+──────────────    ────────  ─────────  ──────────────
+Manhattan         5,411     35.16%     $2,714,327
+Bronx             2,735     21.08%     $1,531,532
+Brooklyn          7,032     20.64%     $857,322
+Queens            9,533     17.43%     $366,226
+Staten Island     3,052     14.41%     $220,216
+
+Key finding — Staten Island paradox: lowest R² of any borough (v11 evaluation),
+yet best MedAPE at 14.41%. Explanation: Staten Island has very low price variance
+(most sales $300K–$700K). The model predicts well in absolute terms, but R²
+penalises a low-variance target disproportionately. MedAPE is the user-relevant
+metric.
+
+Manhattan is hardest: 35.16% MedAPE. Reasons:
   - Co-op board approval discounts (unobservable)
   - Interior finishes, renovation quality (unobservable)
   - Floor number premium in high-rises (partially captured by numfloors)
@@ -567,12 +568,12 @@ Manhattan is hardest: 36.89% MedAPE. Reasons:
 
 Tier              n         MedAPE     MAE (USD)
 ──────────────    ────────  ─────────  ──────────────
-< $500K           6,497     27.71%     $229,607
-$500K – $1M       10,980    14.68%     $179,450
-$1M – $3M         7,978     21.14%     $445,458
-$3M – $10M        1,707     40.58%     $2,169,464
+< $500K           6,497     27.10%     $225,470
+$500K – $1M       10,980    15.12%     $182,149
+$1M – $3M         7,978     21.30%     $454,712
+$3M – $10M        1,707     39.77%     $2,180,172
 
-The sweet spot is $500K–$1M (typical Queens/Brooklyn starter home): 14.68% MedAPE.
+The sweet spot is $500K–$1M (typical Queens/Brooklyn starter home): 15.12% MedAPE.
 The model struggles most below $500K (often Bronx/SI properties with high
 variance from distressed sales) and above $3M (Manhattan luxury, unobservable
 quality signals).

docs/thaman_paper.tex

@@ -725,20 +725,22 @@ diversity for blending to produce a net benefit.
   \label{tab:borough_perf}
   \begin{tabular}{lrrrp{5.5cm}}
     \toprule
-    Borough & $n$ & $R^2$ & MedAPE & Notes \\
+    Borough & $n$ & MedAPE & MAE & Notes \\
     \midrule
-    Staten Island &  3,052 & 0.4103 & 13.46\% & Best accuracy; uniform housing stock \\
-    Queens        &  9,533 & 0.6851 & 17.06\% & Highest volume; best $R^2$ \\
-    Bronx         &  2,735 & 0.6195 & 20.93\% & Mixed housing stock \\
-    Brooklyn      &  7,032 & 0.6206 & 20.89\% & Wide price range across NTAs \\
-    Manhattan     &  5,411 & 0.6141 & 36.66\% & Worst; extreme luxury heterogeneity \\
+    Staten Island &  3,052 & 14.41\% & \$220,216 & Best accuracy; uniform housing stock \\
+    Queens        &  9,533 & 17.43\% & \$366,226 & Highest volume \\
+    Bronx         &  2,735 & 21.08\% & \$1,531,532 & Mixed housing stock \\
+    Brooklyn      &  7,032 & 20.64\% & \$857,322 & Wide price range across NTAs \\
+    Manhattan     &  5,411 & 35.16\% & \$2,714,327 & Worst; extreme luxury heterogeneity \\
     \bottomrule
   \end{tabular}
 \end{table}
 
 \subsubsection{The Staten Island Statistical Paradox}
-Staten Island presents the most instructive diagnostic anomaly: the worst
-$R^2$ (0.4103) combined with the best MedAPE (13.46\%). This divergence
+Staten Island presents the most instructive diagnostic anomaly: in the v11
+evaluation it recorded the worst per-borough $R^2$ (0.4103) combined with the
+best MedAPE (13.46\%) --- and it retains the best MedAPE (14.41\%) in the
+final v22 model. This divergence
 highlights a fundamental mathematical reality. $R^2$ measures:
 \begin{equation}
   R^2 = 1 - \frac{SS_\text{res}}{SS_\text{tot}}
@@ -752,7 +754,7 @@ MedAPE is the correct optimisation target.
 
 \subsubsection{Manhattan Luxury Sub-Market and Co-Op Complexity}
 Manhattan exposes the fundamental limitations of administrative tabular datasets
-for luxury AVM (MedAPE = 36.66\%). Value in the Manhattan luxury market is
+for luxury AVM (MedAPE = 35.16\%). Value in the Manhattan luxury market is
 dictated by subjective, opaque variables entirely absent from municipal tax
 datasets: exact floor level, unobstructed park views, ceiling heights, and
 bespoke interior finishes. Furthermore, co-op buyers do not purchase real
@@ -770,10 +772,10 @@ pricing 10--50\% per square foot below equivalent condominiums.
     \toprule
     Tier & $n$ & MedAPE & Notes \\
     \midrule
-    Under \$500K  &  6,497 & 28.21\% & Distressed sales, foreclosures \\
-    \$500K--\$1M  & 10,980 & 14.53\% & Best accuracy; highest data volume \\
-    \$1M--\$3M    &  7,978 & 20.83\% & Mid-luxury; reasonable accuracy \\
-    Over \$3M     &  1,707 & 40.26\% & Luxury; unique properties, sparse comps \\
+    Under \$500K  &  6,497 & 27.10\% & Distressed sales, foreclosures \\
+    \$500K--\$1M  & 10,980 & 15.12\% & Best accuracy; highest data volume \\
+    \$1M--\$3M    &  7,978 & 21.30\% & Mid-luxury; reasonable accuracy \\
+    Over \$3M     &  1,707 & 39.77\% & Luxury; unique properties, sparse comps \\
     \bottomrule
   \end{tabular}
 \end{table}
@@ -1112,7 +1114,7 @@ prices---consistent with documented Saudi residential market friction
         localised failure invisible to random cross-validation.
   \item The Staten Island paradox demonstrates that $R^2$ and MedAPE measure
         fundamentally different aspects of model quality.
-  \item Manhattan is the hardest borough (MedAPE = 36.66\%). Co-op board approval
+  \item Manhattan is the hardest borough (MedAPE = 35.16\%). Co-op board approval
         discounts, unobservable interior finishes, and view premiums create
         heterogeneity that no tabular dataset can capture.
 \end{enumerate}

docs/thaman_paper.txt

@@ -746,17 +746,19 @@ diversity for blending to produce a net benefit.
 
 7.4 Performance by Borough
 ---------------------------
-  Borough        n       R²      MedAPE    Notes
-  -------        ----    ------  -------   -----
-  Staten Island  3,052   0.4103  13.46%    Best accuracy; uniform housing stock
-  Queens         9,533   0.6851  17.06%    Highest volume; best R²
-  Bronx          2,735   0.6195  20.93%    Mixed housing stock
-  Brooklyn       7,032   0.6206  20.89%    Wide price range across NTAs
-  Manhattan      5,411   0.6141  36.66%    Worst; extreme luxury heterogeneity
+  Borough        n       MedAPE   MAE          Notes
+  -------        ----    -------  ----------   -----
+  Staten Island  3,052   14.41%   $220,216     Best accuracy; uniform housing stock
+  Queens         9,533   17.43%   $366,226     Highest volume
+  Bronx          2,735   21.08%   $1,531,532   Mixed housing stock
+  Brooklyn       7,032   20.64%   $857,322     Wide price range across NTAs
+  Manhattan      5,411   35.16%   $2,714,327   Worst; extreme luxury heterogeneity
 
 7.4.1 The Staten Island Statistical Paradox
-Staten Island presents the most instructive diagnostic anomaly: the worst R²
-(0.4103) combined with the best MedAPE (13.46%). This divergence highlights a
+Staten Island presents the most instructive diagnostic anomaly: in the v11
+evaluation it recorded the worst per-borough R² (0.4103) combined with the best
+MedAPE (13.46%) — and it retains the best MedAPE (14.41%) in the final v22
+model. This divergence highlights a
 fundamental mathematical reality of regression evaluation in homogeneous datasets.
 
 R² measures the proportion of variance explained:
@@ -779,8 +781,8 @@ while keeping absolute predictive errors tight.
 
 7.4.2 Manhattan Luxury Sub-Market and Co-Op Complexity
 Manhattan exposes the fundamental limitations of administrative tabular datasets
-for luxury AVM. While maintaining a moderate R² (0.6141), predictive precision
-degrades to a MedAPE of 36.66%.
+for luxury AVM: predictive precision degrades to a MedAPE of 35.16%, the worst
+of any borough.
 
 In the Manhattan luxury market, value is dictated by subjective, opaque variables
 entirely absent from municipal tax datasets: exact floor level, unobstructed
@@ -803,10 +805,10 @@ maintenance fees, leading to systematic pricing inaccuracies in this segment.
 ------------------------------
   Tier           n        MedAPE    Notes
   ----           ------   -------   -----
-  Under $500K    6,497    28.21%    Distressed sales, foreclosures
-  $500K – $1M    10,980   14.53%    Best accuracy; highest data volume
-  $1M – $3M      7,978    20.83%    Mid-luxury; reasonable accuracy
-  Over $3M       1,707    40.26%    Luxury; unique properties, sparse comps
+  Under $500K    6,497    27.10%    Distressed sales, foreclosures
+  $500K – $1M    10,980   15.12%    Best accuracy; highest data volume
+  $1M – $3M      7,978    21.30%    Mid-luxury; reasonable accuracy
+  Over $3M       1,707    39.77%    Luxury; unique properties, sparse comps
 
 The $500K–$1M tier is the "sweet spot" — highest volume and most consistent
 property characteristics. Below $500K, distressed sales introduce noise the
@@ -846,8 +848,8 @@ The naive approach assigns a single confidence interval to all predictions:
 
 With global MedAPE = 20.32%, a Staten Island $600K property and a Manhattan
 $3M condo both receive ±20.32% intervals. This is dishonest: the Staten Island
-estimate is likely within ±13.5%, while the Manhattan estimate could easily be
-off by ±37%.
+estimate is likely within ±14.4%, while the Manhattan estimate could easily be
+off by ±35%.
 
 8.2 Segment-Adaptive Confidence
 ---------------------------------
@@ -857,7 +859,7 @@ For each prediction, the segment MedAPE is computed as:
 
 Taking the maximum of the two risk dimensions gives the most conservative
 (widest) interval when both risk factors coincide — e.g. Manhattan luxury
-(borough=36.66%, tier=40.26%) → segment_medape = 40.26%.
+(borough=35.16%, tier=39.77%) → segment_medape = 39.77%.
 
   confidence_low  = price × (1 − segment_medape / 100)
   confidence_high = price × (1 + segment_medape / 100)
@@ -885,11 +887,11 @@ index, executing in under 5ms.
 --------------------------------------
   Property                            Grade  Score  Interval
   --------                            -----  -----  --------
-  Queens, 2-family, $700K             A      83     ±17.1%
-  Brooklyn, walk-up, $900K            B      79     ±20.9%
-  Bronx, elevator condo, $400K        C      72     ±28.2%
-  Manhattan, D4, $1.5M                D      63     ±36.7%
-  Manhattan, luxury, $4M              D      60     ±40.3%
+  Queens, 2-family, $700K             A      83     ±17.4%
+  Brooklyn, walk-up, $900K            B      79     ±20.6%
+  Bronx, elevator condo, $400K        C      73     ±27.1%
+  Manhattan, D4, $1.5M                D      65     ±35.2%
+  Manhattan, luxury, $4M              D      60     ±39.8%
 
 ================================================================================
 9. SYSTEM ARCHITECTURE
@@ -1208,7 +1210,7 @@ market friction (CBRE, 2024).
      MedAPE measure fundamentally different aspects of model quality. For a
      user-facing AVM, MedAPE is the correct optimisation target.
 
-  7. Manhattan is the hardest borough (MedAPE=36.66%). Co-op board approval
+  7. Manhattan is the hardest borough (MedAPE=35.16%). Co-op board approval
      discounts, unobservable interior finishes, and view premiums create
      heterogeneity that no tabular dataset can capture.
 

scripts/generate_scatter.py

@@ -290,6 +290,26 @@ medape_val = float(np.median(np.abs(y_actual - y_pred) / np.maximum(y_actual, 1.
 r2_val     = r2_score(np.log1p(y_actual), pred_log)
 print(f"  Scatter: R²={r2_val:.4f} | MedAPE={medape_val:.2f}%")
 
+# Per-borough + per-tier diagnostics (same holdout predictions)
+_BM = {1: "Manhattan", 2: "Bronx", 3: "Brooklyn", 4: "Queens", 5: "Staten Island"}
+_boro_arr = np.array(df_hold["borough"].to_list())
+_ape = np.abs(y_actual - y_pred) / np.maximum(y_actual, 1.0) * 100
+print("  ── Per-borough (holdout) ──")
+for _bn, _bname in _BM.items():
+    _m = _boro_arr == _bn
+    if _m.sum() == 0:
+        continue
+    _r2 = r2_score(np.log1p(y_actual[_m]), pred_log[_m])
+    print(f"    {_bname:<14} n={_m.sum():>6,}  R²={_r2:.4f}  MedAPE={np.median(_ape[_m]):.2f}%")
+print("  ── Per-tier (holdout) ──")
+for _lo, _hi, _tname in [(0, 5e5, "<$500K"), (5e5, 1e6, "$500K–1M"),
+                         (1e6, 3e6, "$1M–3M"), (3e6, 1e7, "$3M–10M")]:
+    _m = (y_actual >= _lo) & (y_actual < _hi)
+    if _m.sum() == 0:
+        continue
+    _r2 = r2_score(np.log1p(y_actual[_m]), pred_log[_m])
+    print(f"    {_tname:<10} n={_m.sum():>6,}  R²={_r2:.4f}  MedAPE={np.median(_ape[_m]):.2f}%")
+
 # ── 8. Sample for scatter plot (2000 pts, stratified by borough) ──
 BOROUGH_MAP = {1:"Manhattan",2:"Bronx",3:"Brooklyn",4:"Queens",5:"Staten Island"}
 boros       = df_hold["borough"].to_list()