Initial drop: CatBoost + XGBoost baselines on House Prices

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+catboost.cbm filter=lfs diff=lfs merge=lfs -text
+figures/fig_dl_09_actual_vs_predicted.png filter=lfs diff=lfs merge=lfs -text
+figures/fig_dl_12_pdp_top6.png filter=lfs diff=lfs merge=lfs -text
+figures/fig_dl_13_monotonicity_check.png filter=lfs diff=lfs merge=lfs -text
+figures/fig_dl_17_combined_dashboard.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,236 @@
+---
+license: mit
+tags:
+  - tabular
+  - regression
+  - catboost
+  - xgboost
+  - ensemble
+  - house-prices
+  - ames-housing
+  - kaggle
+library_name: catboost
+pipeline_tag: tabular-regression
+datasets:
+  - t22000t/house-prices-tabular
+metrics:
+  - gini
+  - mae
+  - rmse
+model-index:
+  - name: house-prices-tabular-models
+    results:
+      - task:
+          type: tabular-regression
+          name: Tabular Regression
+        dataset:
+          type: t22000t/house-prices-tabular
+          name: House Prices - Tabular
+        metrics:
+          - type: gini
+            value: 0.2061
+            name: Test Gini (CatBoost)
+          - type: mae
+            value: 16868
+            name: Test MAE (CatBoost, USD)
+          - type: gini
+            value: 0.2049
+            name: Test Gini (XGBoost)
+          - type: mae
+            value: 17204
+            name: Test MAE (XGBoost, USD)
+---
+
+# House Prices - Tabular Models (CatBoost + XGBoost baseline)
+
+Pre-trained baseline models for the
+[t22000t/house-prices-tabular](https://huggingface.co/datasets/t22000t/house-prices-tabular)
+dataset, produced by the
+[tabular-data-modelling-pipeline](https://github.com/timothy22000/tabular_data_modelling_pipeline).
+
+This is the **v1 baseline drop** - CatBoost + XGBoost trained with sensible
+defaults (no Optuna tuning) on an 80/20 random split. A follow-up release
+will add the six deep-learning architectures (CANN, CANN-GBM, FT-Transformer,
+TabM, LocalGLMnet, DRN) once they're retrained on this dataset.
+
+## Results
+
+| Model | Test Gini | Train Gini | Test MAE (USD) | Test RMSE (USD) | A/E ratio | n params | Training time |
+|---|---|---|---|---|---|---|---|
+| **CatBoost** | **0.2061** | 0.2203 | **16,868** | 27,063 | 1.025 | 1,041 trees | 4.4 s |
+| XGBoost | 0.2049 | 0.2212 | 17,204 | 29,716 | 0.999 | 462 trees | 0.3 s |
+| Stacked ensemble (NNLS) | 0.2049 | 0.2212 | 17,204 | 29,716 | 0.999 | (2 weights) | - |
+
+- **Test set:** 304 rows (20% of 1,460)
+- **Target:** `SalePrice` (USD)
+- **Loss:** Gamma deviance (gamma family, log link)
+- **Target cap:** 99.5th percentile = $555,355 (6 rows winsorised)
+- **Random seed:** 42
+
+The NNLS-stacked ensemble currently degenerates to XGBoost; with more diverse
+base learners (the upcoming DL drop) it will pick a non-trivial blend.
+
+## Files
+
+| File | What it is | Size |
+|---|---|---|
+| `catboost.cbm` | Trained CatBoost model (native format) | 1.2 MB |
+| `xgboost.json` | Trained XGBoost Booster (native JSON format) | 1.3 MB |
+| `evaluation_summary.csv` | Per-model train/test Gini, MAE, RMSE, A/E ratio, gamma deviance | 315 B |
+| `ensemble_weights.json` | NNLS-stacked weights over base predictions | 53 B |
+| `dashboard_dl_models.html` | Interactive Plotly dashboard (Lorenz curves, calibration deciles, ensemble plots) | 4.6 MB |
+| `figures/fig_dl_*.png` | Publication-quality figures matching the dashboard | ~6 MB total |
+| `model_summary.json` | Structured run record (config, metrics, timing) | 3.2 KB |
+
+## Loading and inference
+
+### CatBoost
+
+```python
+from huggingface_hub import hf_hub_download
+from catboost import CatBoostRegressor
+import pandas as pd
+
+path = hf_hub_download(
+    repo_id="t22000t/house-prices-tabular-models",
+    filename="catboost.cbm",
+)
+model = CatBoostRegressor()
+model.load_model(path)
+
+# Load the dataset and predict
+df = pd.read_csv("hf://datasets/t22000t/house-prices-tabular/train.csv")
+# Use only the columns the model was trained on (see model_summary.json)
+features = [
+    "LotArea", "YearBuilt", "YearRemodAdd", "TotalBsmtSF", "1stFlrSF",
+    "2ndFlrSF", "GrLivArea", "FullBath", "BedroomAbvGr", "TotRmsAbvGrd",
+    "GarageCars", "GarageArea", "OverallQual", "OverallCond",
+    "MSZoning", "Street", "LotShape", "Neighborhood", "BldgType",
+    "HouseStyle", "RoofStyle", "ExterQual", "Foundation", "Heating",
+    "CentralAir", "KitchenQual", "SaleType", "SaleCondition",
+]
+preds = model.predict(df[features])
+```
+
+### XGBoost
+
+```python
+from huggingface_hub import hf_hub_download
+import xgboost as xgb
+
+path = hf_hub_download(
+    repo_id="t22000t/house-prices-tabular-models",
+    filename="xgboost.json",
+)
+booster = xgb.Booster()
+booster.load_model(path)
+
+# Predictions require the exact feature order used at training time;
+# easiest path is to re-run the pipeline's preprocessing - see the
+# GitHub repo for the full feature build code.
+```
+
+### Stacked ensemble
+
+```python
+import json
+from huggingface_hub import hf_hub_download
+
+path = hf_hub_download(
+    repo_id="t22000t/house-prices-tabular-models",
+    filename="ensemble_weights.json",
+)
+weights = json.loads(open(path).read())
+# weights = {"catboost": 0.0, "xgboost": 1.0}  (NNLS picked XGBoost only)
+ensemble_pred = weights["catboost"] * cb_pred + weights["xgboost"] * xgb_pred
+```
+
+## Training configuration
+
+| Setting | Value |
+|---|---|
+| Pipeline | [tabular-data-modelling-pipeline](https://github.com/timothy22000/tabular_data_modelling_pipeline) v0.1.0 |
+| Architecture mix | CatBoost + XGBoost (DL models excluded from this drop) |
+| Hyperparameters | Defaults (see `modelling/models/__init__.py`) - **no Optuna tuning** |
+| Optimiser | CatBoost: ordered boosting; XGBoost: hist tree method |
+| Family / link | Gamma / log |
+| Train/test split | Random 80/20, seed 42 |
+| Cap percentile | 99.5 |
+| CV folds | 5 (for stability check) |
+| Hardware | Apple M-series, CPU |
+
+To reproduce exactly, run:
+```bash
+git clone https://github.com/timothy22000/tabular_data_modelling_pipeline
+cd tabular_data_modelling_pipeline
+pip install -e ".[gbm,viz]"
+python scripts/download_data.py --dataset house_prices
+
+OMP_NUM_THREADS=1 python train.py \
+    --config configs/example_house_prices.py \
+    --input data/house_prices.csv \
+    --skip-tuning --skip-interpretability \
+    --architectures catboost xgboost
+```
+
+(`OMP_NUM_THREADS=1` is only needed on macOS arm64 to avoid an OpenMP
+conflict between XGBoost and Python's threading; Linux runs are unaffected.)
+
+## Limitations
+
+- **Defaults only.** No hyperparameter tuning - tuned models would close
+  the train-test gap and likely lift Gini by 0.02-0.05.
+- **GBM only.** This drop omits the six DL architectures. CANN-GBM in
+  particular would likely outperform raw XGBoost since it adds a neural
+  residual on top of the GBM base. v2 will include these.
+- **Random split, not stratified.** SalePrice has a heavy right tail; a
+  stratified split (or quantile-stratified) would give a more representative
+  test set. Default behaviour, kept for reproducibility.
+- **Trained on training set only.** The Kaggle competition's `test.csv`
+  is unlabelled and not used here. To compare against the official
+  leaderboard, train on the full set and submit predictions on test.
+- **Gini scores look modest.** Gini in [0.20, 0.22] is reasonable for
+  this dataset's modest signal-to-noise ratio - Kaggle leaderboard RMSLE
+  is the more conventional metric for House Prices, but the pipeline
+  uses Gini and MAE for cross-comparability across architectures and
+  datasets.
+
+## Intended use
+
+- **Baseline for tabular DL research.** Comparing your new architecture
+  against these numbers.
+- **Teaching.** Demonstrating a calibrated tabular pricing pipeline end
+  to end.
+- **Sanity check.** Make sure your reimplementation of CatBoost/XGBoost
+  on this data hits similar numbers.
+
+## Citation
+
+```bibtex
+@software{tabular_data_modelling_pipeline,
+  author = {Mun, Timothy},
+  title  = {tabular-data-modelling-pipeline},
+  url    = {https://github.com/timothy22000/tabular_data_modelling_pipeline},
+  year   = {2026}
+}
+
+@article{decock2011ames,
+  author  = {De Cock, Dean},
+  title   = {Ames, Iowa: Alternative to the Boston Housing Data},
+  journal = {Journal of Statistics Education},
+  volume  = {19},
+  number  = {3},
+  year    = {2011}
+}
+```
+
+## License
+
+MIT for the model code and pipeline. The underlying dataset is
+distributed under Kaggle competition terms (free use with attribution).
+
+## Related
+
+- 📂 [Dataset: t22000t/house-prices-tabular](https://huggingface.co/datasets/t22000t/house-prices-tabular)
+- 📦 [Pipeline: tabular-data-modelling-pipeline](https://github.com/timothy22000/tabular_data_modelling_pipeline)
+- 🔒 [Privacy Lab Space](https://huggingface.co/spaces/t22000t/privacy-lab) - anonymize tabular data + red-team it

catboost.cbm

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:53867c266dfa9f165312fcec571af3877b8a290e806e79e8b9e0aacefe766383
+size 1216500

ensemble_weights.json

@@ -0,0 +1,5 @@
+{
+  "glm": 0.0,
+  "catboost": 0.0,
+  "xgboost": 1.0
+}

evaluation_summary.csv

@@ -0,0 +1,4 @@
+model,gini_train,gini_test,mae,rmse,cv_rmse,ae_ratio,gamma_deviance,n_params,training_time
+catboost,0.2203,0.2061,16868.04,27062.87,0.1441,1.025,-4.476422,1041,4.4
+xgboost,0.2212,0.2049,17203.89,29715.99,0.1582,0.9985,-4.691965,462,0.3
+stacked_ensemble,0.2212,0.2049,17203.89,29715.99,0.1582,0.9985,-4.691965,3,0.0

model_summary.json

@@ -0,0 +1,132 @@
+{
+  "pipeline": "dl",
+  "timestamp": "2026-05-27T22:08:09.831216",
+  "config": {
+    "seed": 42,
+    "n_tuning_trials": 30,
+    "cv_folds": 5,
+    "quick": false,
+    "architectures": [
+      "catboost",
+      "xgboost"
+    ],
+    "epochs": 300,
+    "patience": 30,
+    "batch_size": 512,
+    "n_ensemble": 3,
+    "catboost_iterations": 2000,
+    "mono_lambda": 0.1
+  },
+  "best_model": "catboost",
+  "double_lift_vs_glm": 20.9939,
+  "glm_gini": 0.009817159273634912,
+  "models": {
+    "catboost": {
+      "metrics_train": {
+        "split": "train",
+        "n": 1156,
+        "n_params": 0,
+        "gini": 0.220273,
+        "mae": 9229.8045,
+        "rmse": 12359.3171,
+        "cv_rmse": 0.069188,
+        "ae_ratio": 1.036369,
+        "mean_actual": 178634.4191,
+        "mean_predicted": 172365.6919,
+        "gamma_deviance": -6.358849
+      },
+      "metrics_test": {
+        "split": "test",
+        "n": 304,
+        "n_params": 0,
+        "gini": 0.206072,
+        "mae": 16868.0377,
+        "rmse": 27062.8666,
+        "cv_rmse": 0.144084,
+        "ae_ratio": 1.02497,
+        "mean_actual": 187827.3717,
+        "mean_predicted": 183251.5518,
+        "gamma_deviance": -4.476422
+      },
+      "training_time": 4.425956964492798,
+      "best_params": {},
+      "n_params": 1041
+    },
+    "xgboost": {
+      "metrics_train": {
+        "split": "train",
+        "n": 1156,
+        "n_params": 0,
+        "gini": 0.221199,
+        "mae": 5759.4073,
+        "rmse": 7959.4927,
+        "cv_rmse": 0.044557,
+        "ae_ratio": 1.002072,
+        "mean_actual": 178634.4191,
+        "mean_predicted": 178265.0061,
+        "gamma_deviance": -2.187904
+      },
+      "metrics_test": {
+        "split": "test",
+        "n": 304,
+        "n_params": 0,
+        "gini": 0.20495,
+        "mae": 17203.8948,
+        "rmse": 29715.992,
+        "cv_rmse": 0.158209,
+        "ae_ratio": 0.998457,
+        "mean_actual": 187827.3717,
+        "mean_predicted": 188117.697,
+        "gamma_deviance": -4.691965
+      },
+      "training_time": 0.27405214309692383,
+      "best_params": {
+        "max_depth": 6,
+        "eta": 0.05,
+        "n_estimators": 1000,
+        "reg_alpha": 0.1,
+        "reg_lambda": 1.0,
+        "subsample": 0.85,
+        "colsample_bytree": 0.85,
+        "early_stopping_rounds": 50
+      },
+      "n_params": 462
+    },
+    "stacked_ensemble": {
+      "metrics_train": {
+        "split": "train",
+        "n": 1156,
+        "n_params": 0,
+        "gini": 0.221199,
+        "mae": 5759.4073,
+        "rmse": 7959.4927,
+        "cv_rmse": 0.044557,
+        "ae_ratio": 1.002072,
+        "mean_actual": 178634.4191,
+        "mean_predicted": 178265.0061,
+        "gamma_deviance": -2.187904
+      },
+      "metrics_test": {
+        "split": "test",
+        "n": 304,
+        "n_params": 0,
+        "gini": 0.20495,
+        "mae": 17203.8948,
+        "rmse": 29715.992,
+        "cv_rmse": 0.158209,
+        "ae_ratio": 0.998457,
+        "mean_actual": 187827.3717,
+        "mean_predicted": 188117.697,
+        "gamma_deviance": -4.691965
+      },
+      "training_time": 0.003686189651489258,
+      "best_params": {},
+      "n_params": 3,
+      "base_weights": {
+        "glm": 0.0,
+        "catboost": 0.0,
+        "xgboost": 1.0
+      }
+    }
+  }
+}