feat(timesfm): complete all three examples with quality docs

- anomaly-detection: full two-phase rewrite (context Z-score + forecast PI),
  2-panel viz, Sep 2023 correctly flagged CRITICAL (z=+3.03)
- covariates-forecasting: v3 rewrite with variable-shadowing bug fixed,
  2x2 shared-axis viz showing actionable covariate decomposition,
  108-row CSV with distinct per-store price arrays
- global-temperature: output/ subfolder reorganization (all 6 output files
  moved, 5 scripts + shell script paths updated)
- SKILL.md: added Examples table, Quality Checklist, Common Mistakes (8 items),
  Validation & Verification with regression assertions
- .gitattributes already at repo root covering all binary types

scientific-skills/timesfm-forecasting/examples/covariates-forecasting/output/covariates_metadata.json

@@ -1,21 +1,24 @@
 {
   "description": "Synthetic retail sales data with covariates for TimesFM XReg demo",
-  "note_on_real_data": "If using a real dataset (e.g., Kaggle Rossmann Store Sales), download it to a temp directory (tempfile.mkdtemp) and do NOT commit it here. This skills directory only ships tiny reference files.",
+  "note_on_real_data": "For real datasets (e.g., Kaggle Rossmann Store Sales), download to tempfile.mkdtemp() -- do NOT commit to this repo.",
   "stores": {
     "store_A": {
       "type": "premium",
       "region": "urban",
-      "base_sales": 1000
+      "base_sales": 1000,
+      "mean_sales_context": 1148.7
     },
     "store_B": {
       "type": "standard",
       "region": "suburban",
-      "base_sales": 750
+      "base_sales": 750,
+      "mean_sales_context": 907.0
     },
     "store_C": {
       "type": "discount",
       "region": "rural",
-      "base_sales": 500
+      "base_sales": 500,
+      "mean_sales_context": 645.3
     }
   },
   "dimensions": {
@@ -27,10 +30,10 @@
   },
   "covariates": {
     "dynamic_numerical": [
-      "price",
-      "promotion"
+      "price"
     ],
     "dynamic_categorical": [
+      "promotion",
       "holiday",
       "day_of_week"
     ],
@@ -39,12 +42,18 @@
       "region"
     ]
   },
-  "xreg_modes": {
-    "xreg + timesfm": "Fit regression on residuals after TimesFM forecast",
-    "timesfm + xreg": "TimesFM forecasts residuals after regression fit"
+  "effect_magnitudes": {
+    "holiday": "+200 units per holiday week",
+    "promotion": "+150 units per promotion week",
+    "price": "-20 units per $1 above base price"
   },
-  "bug_fixes": [
-    "v2: Fixed variable-shadowing in generate_sales_data() \u2014 inner dict comprehension `{store_id: ... for store_id in stores}` was overwriting the outer loop variable, causing all stores to get identical covariate arrays. Fixed by using separate per-store dicts during the loop.",
-    "v2: Reduced CONTEXT_LEN from 48 \u2192 24 weeks; CSV now 90 rows (was 180)."
+  "xreg_modes": {
+    "xreg + timesfm": "Regression on TimesFM residuals (default)",
+    "timesfm + xreg": "TimesFM on regression residuals"
+  },
+  "bug_fixes_history": [
+    "v1: Variable-shadowing -- all stores had identical covariates",
+    "v2: Fixed shadowing; CONTEXT_LEN 48->24",
+    "v3: Added component decomposition (base, price/promo/holiday effects); 2x2 sharex viz"
   ]
 }

scientific-skills/timesfm-forecasting/examples/covariates-forecasting/output/sales_with_covariates.csv

@@ -1,109 +1,109 @@
-store_id,week,split,sales,price,promotion,holiday,day_of_week,store_type,region
-store_A,0,context,1372.64,11.6299,1,1,0,premium,urban
-store_A,1,context,965.54,11.9757,0,0,1,premium,urban
-store_A,2,context,1076.92,11.7269,0,0,2,premium,urban
-store_A,3,context,1094.09,12.1698,0,0,3,premium,urban
-store_A,4,context,970.18,11.9372,0,0,4,premium,urban
-store_A,5,context,1010.04,12.3327,0,0,5,premium,urban
-store_A,6,context,1098.7,12.2003,0,0,6,premium,urban
-store_A,7,context,1097.79,11.8124,0,0,0,premium,urban
-store_A,8,context,1114.81,12.3323,0,0,1,premium,urban
-store_A,9,context,1084.8,12.3048,0,0,2,premium,urban
-store_A,10,context,1339.72,11.8875,1,0,3,premium,urban
-store_A,11,context,1395.22,11.7883,0,1,4,premium,urban
-store_A,12,context,1158.92,12.1825,0,0,5,premium,urban
-store_A,13,context,1228.57,11.6398,0,0,6,premium,urban
-store_A,14,context,1198.65,11.6999,0,0,0,premium,urban
-store_A,15,context,1138.98,11.5074,0,0,1,premium,urban
-store_A,16,context,1186.2,12.2869,0,0,2,premium,urban
-store_A,17,context,1122.3,12.1649,0,0,3,premium,urban
-store_A,18,context,1212.12,12.2052,0,0,4,premium,urban
-store_A,19,context,1161.74,12.2807,0,0,5,premium,urban
-store_A,20,context,1157.89,11.9589,0,0,6,premium,urban
-store_A,21,context,1126.39,12.0687,0,0,0,premium,urban
-store_A,22,context,1224.8,11.6398,0,0,1,premium,urban
-store_A,23,context,1350.44,11.6145,0,1,2,premium,urban
-store_A,24,horizon,1119.15,12.1684,0,0,3,premium,urban
-store_A,25,horizon,1120.03,11.9711,0,0,4,premium,urban
-store_A,26,horizon,1155.31,12.0652,0,0,5,premium,urban
-store_A,27,horizon,1285.92,12.265,1,0,6,premium,urban
-store_A,28,horizon,1284.01,12.1347,1,0,0,premium,urban
-store_A,29,horizon,1130.01,12.0536,0,0,1,premium,urban
-store_A,30,horizon,1209.43,12.0592,0,0,2,premium,urban
-store_A,31,horizon,1231.79,11.804,1,0,3,premium,urban
-store_A,32,horizon,1077.46,11.5308,0,0,4,premium,urban
-store_A,33,horizon,1050.73,11.9367,0,0,5,premium,urban
-store_A,34,horizon,1124.21,11.7146,0,0,6,premium,urban
-store_A,35,horizon,1344.73,11.9085,0,1,0,premium,urban
-store_B,0,context,1053.03,9.9735,1,1,0,standard,suburban
-store_B,1,context,903.51,9.767,1,0,1,standard,suburban
-store_B,2,context,826.82,9.8316,0,0,2,standard,suburban
-store_B,3,context,709.93,10.0207,0,0,3,standard,suburban
-store_B,4,context,834.42,9.9389,0,0,4,standard,suburban
-store_B,5,context,847.01,9.5216,0,0,5,standard,suburban
-store_B,6,context,802.58,10.3263,0,0,6,standard,suburban
-store_B,7,context,770.87,10.3962,0,0,0,standard,suburban
-store_B,8,context,873.1,9.6402,0,0,1,standard,suburban
-store_B,9,context,844.74,10.054,0,0,2,standard,suburban
-store_B,10,context,1050.46,9.6086,1,0,3,standard,suburban
-store_B,11,context,1085.99,10.1722,0,1,4,standard,suburban
-store_B,12,context,978.74,9.7812,0,0,5,standard,suburban
-store_B,13,context,1033.59,10.1594,1,0,6,standard,suburban
-store_B,14,context,846.06,10.227,0,0,0,standard,suburban
-store_B,15,context,906.93,10.2686,0,0,1,standard,suburban
-store_B,16,context,922.35,9.6077,0,0,2,standard,suburban
-store_B,17,context,1111.93,10.416,1,0,3,standard,suburban
-store_B,18,context,946.95,9.7302,0,0,4,standard,suburban
-store_B,19,context,923.2,9.5374,0,0,5,standard,suburban
-store_B,20,context,963.38,10.0549,0,0,6,standard,suburban
-store_B,21,context,978.7,9.8709,1,0,0,standard,suburban
-store_B,22,context,840.39,10.3298,0,0,1,standard,suburban
-store_B,23,context,1019.22,10.3083,0,1,2,standard,suburban
-store_B,24,horizon,848.1,9.8171,0,0,3,standard,suburban
-store_B,25,horizon,777.91,10.4529,0,0,4,standard,suburban
-store_B,26,horizon,883.44,9.7909,0,0,5,standard,suburban
-store_B,27,horizon,827.78,10.0151,0,0,6,standard,suburban
-store_B,28,horizon,762.41,9.756,0,0,0,standard,suburban
-store_B,29,horizon,763.79,10.436,0,0,1,standard,suburban
-store_B,30,horizon,838.41,9.6646,0,0,2,standard,suburban
-store_B,31,horizon,860.45,9.5449,0,0,3,standard,suburban
-store_B,32,horizon,904.82,9.9351,0,0,4,standard,suburban
-store_B,33,horizon,1084.74,10.4924,1,0,5,standard,suburban
-store_B,34,horizon,808.09,10.3917,0,0,6,standard,suburban
-store_B,35,horizon,938.26,10.2486,0,1,0,standard,suburban
-store_C,0,context,709.43,7.1053,0,1,0,discount,rural
-store_C,1,context,649.01,7.0666,1,0,1,discount,rural
-store_C,2,context,660.66,7.5944,1,0,2,discount,rural
-store_C,3,context,750.17,7.1462,1,0,3,discount,rural
-store_C,4,context,726.88,7.8247,1,0,4,discount,rural
-store_C,5,context,639.97,7.3103,0,0,5,discount,rural
-store_C,6,context,580.71,7.1439,0,0,6,discount,rural
-store_C,7,context,549.13,7.921,0,0,0,discount,rural
-store_C,8,context,597.79,7.1655,0,0,1,discount,rural
-store_C,9,context,627.48,7.2847,0,0,2,discount,rural
-store_C,10,context,634.26,7.1536,0,0,3,discount,rural
-store_C,11,context,928.07,7.1155,1,1,4,discount,rural
-store_C,12,context,643.37,7.0211,0,0,5,discount,rural
-store_C,13,context,652.8,7.0554,0,0,6,discount,rural
-store_C,14,context,766.65,7.1746,0,0,0,discount,rural
-store_C,15,context,737.37,7.0534,0,0,1,discount,rural
-store_C,16,context,589.02,7.5911,0,0,2,discount,rural
-store_C,17,context,613.06,7.6807,0,0,3,discount,rural
-store_C,18,context,556.25,7.3936,0,0,4,discount,rural
-store_C,19,context,596.46,7.318,0,0,5,discount,rural
-store_C,20,context,632.0,7.5045,0,0,6,discount,rural
-store_C,21,context,662.1,7.875,0,0,0,discount,rural
-store_C,22,context,558.0,7.8511,0,0,1,discount,rural
-store_C,23,context,769.38,7.0435,0,1,2,discount,rural
-store_C,24,horizon,482.94,7.1815,0,0,3,discount,rural
-store_C,25,horizon,571.69,7.2367,0,0,4,discount,rural
-store_C,26,horizon,666.89,7.2494,1,0,5,discount,rural
-store_C,27,horizon,677.55,7.5712,1,0,6,discount,rural
-store_C,28,horizon,503.9,7.4163,0,0,0,discount,rural
-store_C,29,horizon,541.34,7.0493,0,0,1,discount,rural
-store_C,30,horizon,443.17,7.3736,0,0,2,discount,rural
-store_C,31,horizon,596.87,7.5238,1,0,3,discount,rural
-store_C,32,horizon,628.12,7.1017,0,0,4,discount,rural
-store_C,33,horizon,586.61,7.8335,1,0,5,discount,rural
-store_C,34,horizon,456.82,7.052,0,0,6,discount,rural
-store_C,35,horizon,782.3,7.9248,0,1,0,discount,rural
+store_id,week,split,sales,base_sales,price,price_effect,promotion,holiday,day_of_week,store_type,region
+store_A,0,context,1369.59,1012.19,11.6299,7.4,1,1,0,premium,urban
+store_A,1,context,973.53,973.04,11.9757,0.49,0,0,1,premium,urban
+store_A,2,context,1064.63,1059.16,11.7269,5.46,0,0,2,premium,urban
+store_A,3,context,1077.59,1080.99,12.1698,-3.4,0,0,3,premium,urban
+store_A,4,context,980.39,979.14,11.9372,1.26,0,0,4,premium,urban
+store_A,5,context,1011.7,1018.36,12.3327,-6.65,0,0,5,premium,urban
+store_A,6,context,1084.16,1088.16,12.2003,-4.01,0,0,6,premium,urban
+store_A,7,context,1085.98,1082.23,11.8124,3.75,0,0,0,premium,urban
+store_A,8,context,1098.52,1105.17,12.3323,-6.65,0,0,1,premium,urban
+store_A,9,context,1075.62,1081.71,12.3048,-6.1,0,0,2,premium,urban
+store_A,10,context,1312.23,1159.98,11.8875,2.25,1,0,3,premium,urban
+store_A,11,context,1368.02,1163.79,11.7883,4.23,0,1,4,premium,urban
+store_A,12,context,1138.41,1142.06,12.1825,-3.65,0,0,5,premium,urban
+store_A,13,context,1197.29,1190.09,11.6398,7.2,0,0,6,premium,urban
+store_A,14,context,1174.12,1168.12,11.6999,6.0,0,0,0,premium,urban
+store_A,15,context,1128.16,1118.3,11.5074,9.85,0,0,1,premium,urban
+store_A,16,context,1163.81,1169.55,12.2869,-5.74,0,0,2,premium,urban
+store_A,17,context,1114.18,1117.48,12.1649,-3.3,0,0,3,premium,urban
+store_A,18,context,1186.87,1190.98,12.2052,-4.1,0,0,4,premium,urban
+store_A,19,context,1147.27,1152.88,12.2807,-5.61,0,0,5,premium,urban
+store_A,20,context,1146.48,1145.66,11.9589,0.82,0,0,6,premium,urban
+store_A,21,context,1121.83,1123.21,12.0687,-1.37,0,0,0,premium,urban
+store_A,22,context,1203.28,1196.08,11.6398,7.2,0,0,1,premium,urban
+store_A,23,context,1344.9,1137.19,11.6145,7.71,0,1,2,premium,urban
+store_A,24,horizon,1118.64,1122.01,12.1684,-3.37,0,0,3,premium,urban
+store_A,25,horizon,1121.14,1120.56,11.9711,0.58,0,0,4,premium,urban
+store_A,26,horizon,1149.99,1151.29,12.0652,-1.3,0,0,5,premium,urban
+store_A,27,horizon,1284.67,1139.97,12.265,-5.3,1,0,6,premium,urban
+store_A,28,horizon,1284.67,1137.36,12.1347,-2.69,1,0,0,premium,urban
+store_A,29,horizon,1132.79,1133.86,12.0536,-1.07,0,0,1,premium,urban
+store_A,30,horizon,1197.3,1198.49,12.0592,-1.18,0,0,2,premium,urban
+store_A,31,horizon,1247.22,1093.3,11.804,3.92,1,0,3,premium,urban
+store_A,32,horizon,1095.84,1086.46,11.5308,9.38,0,0,4,premium,urban
+store_A,33,horizon,1073.83,1072.57,11.9367,1.27,0,0,5,premium,urban
+store_A,34,horizon,1134.51,1128.8,11.7146,5.71,0,0,6,premium,urban
+store_A,35,horizon,1351.15,1149.32,11.9085,1.83,0,1,0,premium,urban
+store_B,0,context,1062.53,712.0,9.9735,0.53,1,1,0,standard,suburban
+store_B,1,context,904.49,749.83,9.767,4.66,1,0,1,standard,suburban
+store_B,2,context,813.63,810.26,9.8316,3.37,0,0,2,standard,suburban
+store_B,3,context,720.11,720.53,10.0207,-0.41,0,0,3,standard,suburban
+store_B,4,context,820.78,819.55,9.9389,1.22,0,0,4,standard,suburban
+store_B,5,context,833.27,823.7,9.5216,9.57,0,0,5,standard,suburban
+store_B,6,context,795.26,801.78,10.3263,-6.53,0,0,6,standard,suburban
+store_B,7,context,770.37,778.29,10.3962,-7.92,0,0,0,standard,suburban
+store_B,8,context,855.92,848.72,9.6402,7.2,0,0,1,standard,suburban
+store_B,9,context,832.33,833.41,10.054,-1.08,0,0,2,standard,suburban
+store_B,10,context,1029.44,871.61,9.6086,7.83,1,0,3,standard,suburban
+store_B,11,context,1066.35,869.8,10.1722,-3.44,0,1,4,standard,suburban
+store_B,12,context,942.86,938.49,9.7812,4.38,0,0,5,standard,suburban
+store_B,13,context,1015.99,869.18,10.1594,-3.19,1,0,6,standard,suburban
+store_B,14,context,836.44,840.98,10.227,-4.54,0,0,0,standard,suburban
+store_B,15,context,885.72,891.1,10.2686,-5.37,0,0,1,standard,suburban
+store_B,16,context,901.45,893.6,9.6077,7.85,0,0,2,standard,suburban
+store_B,17,context,1080.63,938.95,10.416,-8.32,1,0,3,standard,suburban
+store_B,18,context,922.14,916.74,9.7302,5.4,0,0,4,standard,suburban
+store_B,19,context,904.66,895.41,9.5374,9.25,0,0,5,standard,suburban
+store_B,20,context,935.48,936.58,10.0549,-1.1,0,0,6,standard,suburban
+store_B,21,context,979.23,826.64,9.8709,2.58,1,0,0,standard,suburban
+store_B,22,context,837.49,844.09,10.3298,-6.6,0,0,1,standard,suburban
+store_B,23,context,1021.39,827.56,10.3083,-6.17,0,1,2,standard,suburban
+store_B,24,horizon,847.21,843.55,9.8171,3.66,0,0,3,standard,suburban
+store_B,25,horizon,789.27,798.33,10.4529,-9.06,0,0,4,standard,suburban
+store_B,26,horizon,877.09,872.91,9.7909,4.18,0,0,5,standard,suburban
+store_B,27,horizon,832.42,832.72,10.0151,-0.3,0,0,6,standard,suburban
+store_B,28,horizon,781.9,777.02,9.756,4.88,0,0,0,standard,suburban
+store_B,29,horizon,781.04,789.76,10.436,-8.72,0,0,1,standard,suburban
+store_B,30,horizon,844.57,837.86,9.6646,6.71,0,0,2,standard,suburban
+store_B,31,horizon,863.43,854.33,9.5449,9.1,0,0,3,standard,suburban
+store_B,32,horizon,898.12,896.82,9.9351,1.3,0,0,4,standard,suburban
+store_B,33,horizon,1070.58,930.42,10.4924,-9.85,1,0,5,standard,suburban
+store_B,34,horizon,820.4,828.24,10.3917,-7.83,0,0,6,standard,suburban
+store_B,35,horizon,965.86,770.83,10.2486,-4.97,0,1,0,standard,suburban
+store_C,0,context,709.12,501.23,7.1053,7.89,0,1,0,discount,rural
+store_C,1,context,651.44,492.78,7.0666,8.67,1,0,1,discount,rural
+store_C,2,context,659.15,511.04,7.5944,-1.89,1,0,2,discount,rural
+store_C,3,context,733.06,575.98,7.1462,7.08,1,0,3,discount,rural
+store_C,4,context,712.21,568.7,7.8247,-6.49,1,0,4,discount,rural
+store_C,5,context,615.23,611.44,7.3103,3.79,0,0,5,discount,rural
+store_C,6,context,568.99,561.87,7.1439,7.12,0,0,6,discount,rural
+store_C,7,context,541.12,549.54,7.921,-8.42,0,0,0,discount,rural
+store_C,8,context,583.57,576.88,7.1655,6.69,0,0,1,discount,rural
+store_C,9,context,607.34,603.04,7.2847,4.31,0,0,2,discount,rural
+store_C,10,context,613.79,606.86,7.1536,6.93,0,0,3,discount,rural
+store_C,11,context,919.49,561.8,7.1155,7.69,1,1,4,discount,rural
+store_C,12,context,622.61,613.04,7.0211,9.58,0,0,5,discount,rural
+store_C,13,context,630.52,621.63,7.0554,8.89,0,0,6,discount,rural
+store_C,14,context,721.62,715.12,7.1746,6.51,0,0,0,discount,rural
+store_C,15,context,699.18,690.25,7.0534,8.93,0,0,1,discount,rural
+store_C,16,context,578.85,580.67,7.5911,-1.82,0,0,2,discount,rural
+store_C,17,context,598.23,601.84,7.6807,-3.61,0,0,3,discount,rural
+store_C,18,context,554.43,552.3,7.3936,2.13,0,0,4,discount,rural
+store_C,19,context,587.39,583.75,7.318,3.64,0,0,5,discount,rural
+store_C,20,context,615.58,615.67,7.5045,-0.09,0,0,6,discount,rural
+store_C,21,context,638.68,646.18,7.875,-7.5,0,0,0,discount,rural
+store_C,22,context,555.99,563.01,7.8511,-7.02,0,0,1,discount,rural
+store_C,23,context,768.83,559.7,7.0435,9.13,0,1,2,discount,rural
+store_C,24,horizon,499.62,493.25,7.1815,6.37,0,0,3,discount,rural
+store_C,25,horizon,570.9,565.64,7.2367,5.27,0,0,4,discount,rural
+store_C,26,horizon,677.52,522.5,7.2494,5.01,1,0,5,discount,rural
+store_C,27,horizon,685.25,536.68,7.5712,-1.42,1,0,6,discount,rural
+store_C,28,horizon,517.46,515.78,7.4163,1.67,0,0,0,discount,rural
+store_C,29,horizon,549.38,540.36,7.0493,9.01,0,0,1,discount,rural
+store_C,30,horizon,470.04,467.51,7.3736,2.53,0,0,2,discount,rural
+store_C,31,horizon,622.9,473.37,7.5238,-0.48,1,0,3,discount,rural
+store_C,32,horizon,620.09,612.12,7.1017,7.97,0,0,4,discount,rural
+store_C,33,horizon,614.45,471.12,7.8335,-6.67,1,0,5,discount,rural
+store_C,34,horizon,484.25,475.29,7.052,8.96,0,0,6,discount,rural
+store_C,35,horizon,781.64,590.14,7.9248,-8.5,0,1,0,discount,rural