HARBOUR: A non-neural harmonic learner with exact case-based explanations and calibrated rejection for tabular data
Description
Research hypothesis: A non-neural learner built from screened Neumann potentials on a graph of training records (HARBOUR) can give exact case-based explanations, detect inputs from unseen classes as well as strong combined baselines, and learn from few labels when labels are chosen by a rule derived from a discrete trace Poincaré inequality, while staying close in accuracy to tree ensembles and tabular neural networks. What the data are: Code, raw experiment results and analysis scripts for the article “HARBOUR: A non-neural harmonic learner with exact case-based explanations and calibrated rejection for tabular data”. No new primary data are included. The eleven benchmark datasets (NSL-KDD, UNSW-NB15, Heart disease, Diabetes 130-US, Dry Bean, Covertype, Dermatology, Soybean, ann-thyroid, Satimage, Pendigits) are public; the included script downloads them and checks their SHA-256 checksums. How the data were gathered: Experiments ran on Google Colab (NVIDIA T4 GPU). HARBOUR was compared with logistic regression, k-NN, random forest, XGBoost, MLP, ResNet and FT-Transformer, each with the same budget of eight tuned configurations. Each line of results/r2_<experiment>.jsonl stores one run and the metrics of every method (macro-F1, balanced accuracy, calibration error, unseen-class AUROC, selective risk, running time). E1E2/E1E2v2: main benchmark of six datasets with shift and unknown-class splits. E2C: five confirmation datasets, run after the decision criteria were fixed. E3: label efficiency. E4: explanations. E5: ablations. E8: running time. Notable findings: On the confirmation datasets, HARBOUR’s rejection rule reached a mean AUROC of 0.879 for held-out classes, the highest of 21 scores and level with XGBoost plus nearest-neighbour distance (0.876). Its attributions were exact, faithful under refitting and about 287 times faster than KernelSHAP. Theory-guided label selection improved macro-F1 (p < 1e-9). HARBOUR was about 0.025 macro-F1 below random forest, XGBoost and an MLP. Its limits are dependence on the input distance and over-rejection under covariate shift. How to use: The README maps each file to the article. The analysis folder rebuilds every table and figure from the results folder in a few minutes without re-running models. Class HARBOUR2 in the code is the model of the article; class HARBOUR has the same classifier with an earlier rejection rule, used for comparison. notebook/HARBOUR_reproduce.ipynb repeats all experiments. Licences: code MIT, results CC BY 4.0.
Files
Steps to reproduce
Software: Python 3.10 or later with the packages in requirements.txt (NumPy, SciPy, pandas, scikit-learn, XGBoost, SHAP) and PyTorch for the neural baselines. All experiments ran on Google Colab with an NVIDIA T4 GPU and 2 CPU cores; a GPU is optional for HARBOUR. Data: run “python scripts/get_data.py --dest data/raw”. The script downloads the eleven public datasets (NSL-KDD, UNSW-NB15, Heart disease, Diabetes 130-US, Dry Bean, Covertype and the PMLB versions of Dermatology, Soybean, ann-thyroid, Satimage and Pendigits) and checks every file against a stored SHA-256 checksum. Then set HARBOUR_DATA=data/raw. Protocol: each training pool is split into fit, calibration and selection parts (stratified; fit at most 20,000 records). Every tuned method receives the same budget of eight configurations, chosen by macro-F1 on the selection split of the first seed. Calibration data are used only for early stopping, temperatures and rejection thresholds. Test sets with shifted or unseen classes are never used for tuning. Experiments: run “python scripts/run_round2.py --exp <name> --out results_new” with name = E1E2 and E1E2v2 (six main datasets), E2C with “--datasets dermatology soybean ann_thyroid satimage pendigits” (confirmation datasets), E3 (label efficiency), E4 (explanations), E5 (ablations) and E8 (running time). “python scripts/synthetic_suite.py” reproduces the choice of the rejection rule. Runs are saved one by one and finished runs are skipped, so an interrupted job can be restarted. The notebook notebook/HARBOUR_reproduce.ipynb runs all steps in order on Colab (about 10-12 hours in total). Tables and figures: without re-running any model, run the scripts in analysis/ on the included results folder (analyse_main.py, analyse_rejection.py, make_tables.py, fig_confirmation.py, make_figures.py, fig_labels_runtime.py). They rebuild every table and figure of the article in a few minutes. The exact commands are in README.md. Statistics: paired Wilcoxon signed-rank tests over datasets, splits and seeds; Friedman test with the Nemenyi critical difference over datasets. Random seeds are fixed in the code.