mjboost 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
mjboost-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Minjong Cheon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,5 @@
1
+ include README.md LICENSE
2
+ recursive-include tests *.py
3
+ include examples/quickstart.py
4
+ prune dev
5
+ prune dist
mjboost-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,140 @@
1
+ Metadata-Version: 2.4
2
+ Name: mjboost
3
+ Version: 0.1.0
4
+ Summary: Gradient boosting with Kolmogorov-Arnold units: interpretable regression and binary classification beyond pairwise interactions, with an exact functional ANOVA of the fitted model
5
+ Author: Minjong Cheon
6
+ License-Expression: MIT
7
+ Keywords: gradient boosting,interpretable machine learning,generalized additive model,Kolmogorov-Arnold,functional ANOVA,tabular data
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: numpy>=1.22
16
+ Requires-Dist: scipy>=1.8
17
+ Requires-Dist: numba>=0.56
18
+ Requires-Dist: pandas>=1.4
19
+ Requires-Dist: scikit-learn>=1.1
20
+ Provides-Extra: plot
21
+ Requires-Dist: matplotlib>=3.5; extra == "plot"
22
+ Provides-Extra: test
23
+ Requires-Dist: pytest; extra == "test"
24
+ Requires-Dist: matplotlib>=3.5; extra == "test"
25
+ Dynamic: license-file
26
+
27
+ # MJBoost
28
+
29
+ Gradient boosting with Kolmogorov–Arnold units for interpretable regression and binary classification
30
+ beyond pairwise interactions.
31
+
32
+ Each boosting round adds one Kolmogorov–Arnold (KA) unit
33
+
34
+ h(x) = g( φ_1(x_1) + φ_2(x_2) + … )
35
+
36
+ whose inner functions φ and outer function g are penalized splines, fitted in closed form by alternating
37
+ penalized least squares from principal Hessian directions of the residual. An additive spline backbone
38
+ carries the main effects, and categorical and missing inputs enter the units directly. Because a unit depends
39
+ on each input only through one inner function, the fitted model has an **exact functional ANOVA
40
+ decomposition** into main effects, pair effects and a higher-order remainder, which one-dimensional
41
+ convolutions compute. The model reads as curves and surfaces where the data allow, and the decomposition
42
+ measures the higher-order part where they do not.
43
+
44
+ ## Installation
45
+
46
+ ```bash
47
+ pip install mjboost # once released on PyPI
48
+ pip install "mjboost[plot]" # with matplotlib for the figures
49
+ ```
50
+
51
+ From a copy of this repository:
52
+
53
+ ```bash
54
+ pip install .
55
+ ```
56
+
57
+ Requirements: Python ≥ 3.9, numpy, scipy, numba, pandas, scikit-learn. The first fit in a new environment
58
+ compiles the numba kernels (tens of seconds); later sessions load them from the cache.
59
+
60
+ ## Quick start
61
+
62
+ ```python
63
+ import pandas as pd
64
+ from mjboost import MJBoostRegressor
65
+
66
+ model = MJBoostRegressor().fit(X_train, y_train) # pandas DataFrame or NumPy array
67
+ pred = model.predict(X_test)
68
+ ```
69
+
70
+ DataFrame columns of type `category`, `object`, `bool` or `string` are categorical (each enters a unit as one
71
+ input); numeric columns may contain `NaN`. A level not seen in training gets the reference value of its
72
+ input. `cat_features` overrides the detection with a list of column names or positions.
73
+
74
+ Binary classification:
75
+
76
+ ```python
77
+ from mjboost import MJBoostClassifier
78
+
79
+ clf = MJBoostClassifier().fit(X_train, y_train) # any two labels
80
+ proba = clf.predict_proba(X_test) # columns follow clf.classes_
81
+ ```
82
+
83
+ Both estimators follow the scikit-learn API (`get_params`, `clone`, `Pipeline`, `cross_val_score`, pickling).
84
+
85
+ ## Reading the fitted model
86
+
87
+ ```python
88
+ ex = model.explain() # exact functional ANOVA (log-odds scale for a classifier)
89
+
90
+ ex.shares(X_test) # variance shares of main / pair / higher-order parts, R² of truncations
91
+ ex.importance(X_test) # spread of every main and pair effect, largest first
92
+ ex.main_effect("age") # DataFrame: value, effect (one row per level for a categorical input)
93
+ xa, xb, F = ex.pair_effect("lat", "long")
94
+ C = ex.components(X_test) # f0, main effects, pair effects, remainder, prediction per row
95
+
96
+ ex.plot_main("age"); ex.plot_pair("lat", "long"); ex.plot_shares(X_test)
97
+ ```
98
+
99
+ The decomposition is taken with respect to the product of the training marginals:
100
+ f0 = E f, f_j = E[f | x_j] − f0, f_jk = E[f | x_j, x_k] − f_j − f_k − f0, and the remainder holds the
101
+ interactions of order three and higher. At every row the parts sum to the prediction.
102
+
103
+ ## Model selection and options
104
+
105
+ By default (`selection="two_race"`, the setting of the paper) five-fold cross-validation inside the training
106
+ data chooses the additive backbone (on or off), the unit resolution (16 or 32 interior knots), the column
107
+ fraction (0.5 or 1) and support pruning (on or off). The candidates are raced on the first inner fold with
108
+ stops at 100 and 200 units, and three finalists continue on the other folds. Two races run on the same
109
+ folds, one over the eight candidates with support pruning and one over all sixteen; the winner of the second
110
+ replaces that of the first when its cross-validated loss is lower. The prediction is the average of the five
111
+ fold models. `model.selection_` reports the winning race, its candidate and the inner loss of each race.
112
+
113
+ | Parameter | Default | Meaning |
114
+ |---|---|---|
115
+ | `selection` | `"two_race"` | `"pruned"`: the first race only (about a third of the computation); `"all"`: the second only |
116
+ | `cat_features` | `"auto"` | categorical columns: `"auto"`, `None`, or a list of names / positions |
117
+ | `max_units` | 4000 | maximum number of units per fold model (early stopping decides) |
118
+ | `learning_rate` | 0.3 | shrinkage of every unit |
119
+ | `max_inputs_per_unit` | 12 | cap on the inputs a unit may use |
120
+ | `n_jobs` | 1 | processes for the inner cross-validation (the result does not depend on it) |
121
+ | `random_state` | 0 | seed of the inner folds and column draws |
122
+ | `params` | `None` | dict of further settings of the underlying `KAUnitBoost` (for experts) |
123
+
124
+ ## Results
125
+
126
+ On the 35 regression tasks of OpenML-CTR23 (ten folds, one thread per fit), MJBoost has a lower test RMSE than
127
+ EBM on 21 tasks, a statistically equal one on 12 and a higher one on 2, with a 29.1% lower geometric-mean
128
+ RMSE; against tuned LightGBM the geometric-mean RMSE is 13.2% lower. On synthetic targets of interaction
129
+ order three to six its test error is up to 13 times lower than that of EBM. On 32 binary tasks of
130
+ OpenML-CC18 its test log-loss is on par with that of EBM. Over the CTR23 run MJBoost used 130 CPU-hours,
131
+ EBM 68 and tuned LightGBM 19.
132
+
133
+ ## Citation
134
+
135
+ Minjong Cheon, Hanseon Joo and Eunji Lee. Gradient Boosting with Kolmogorov–Arnold Units for Interpretable
136
+ Regression beyond Pairwise Interactions. 2026.
137
+
138
+ ## License
139
+
140
+ MIT
@@ -0,0 +1,114 @@
1
+ # MJBoost
2
+
3
+ Gradient boosting with Kolmogorov–Arnold units for interpretable regression and binary classification
4
+ beyond pairwise interactions.
5
+
6
+ Each boosting round adds one Kolmogorov–Arnold (KA) unit
7
+
8
+ h(x) = g( φ_1(x_1) + φ_2(x_2) + … )
9
+
10
+ whose inner functions φ and outer function g are penalized splines, fitted in closed form by alternating
11
+ penalized least squares from principal Hessian directions of the residual. An additive spline backbone
12
+ carries the main effects, and categorical and missing inputs enter the units directly. Because a unit depends
13
+ on each input only through one inner function, the fitted model has an **exact functional ANOVA
14
+ decomposition** into main effects, pair effects and a higher-order remainder, which one-dimensional
15
+ convolutions compute. The model reads as curves and surfaces where the data allow, and the decomposition
16
+ measures the higher-order part where they do not.
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ pip install mjboost # once released on PyPI
22
+ pip install "mjboost[plot]" # with matplotlib for the figures
23
+ ```
24
+
25
+ From a copy of this repository:
26
+
27
+ ```bash
28
+ pip install .
29
+ ```
30
+
31
+ Requirements: Python ≥ 3.9, numpy, scipy, numba, pandas, scikit-learn. The first fit in a new environment
32
+ compiles the numba kernels (tens of seconds); later sessions load them from the cache.
33
+
34
+ ## Quick start
35
+
36
+ ```python
37
+ import pandas as pd
38
+ from mjboost import MJBoostRegressor
39
+
40
+ model = MJBoostRegressor().fit(X_train, y_train) # pandas DataFrame or NumPy array
41
+ pred = model.predict(X_test)
42
+ ```
43
+
44
+ DataFrame columns of type `category`, `object`, `bool` or `string` are categorical (each enters a unit as one
45
+ input); numeric columns may contain `NaN`. A level not seen in training gets the reference value of its
46
+ input. `cat_features` overrides the detection with a list of column names or positions.
47
+
48
+ Binary classification:
49
+
50
+ ```python
51
+ from mjboost import MJBoostClassifier
52
+
53
+ clf = MJBoostClassifier().fit(X_train, y_train) # any two labels
54
+ proba = clf.predict_proba(X_test) # columns follow clf.classes_
55
+ ```
56
+
57
+ Both estimators follow the scikit-learn API (`get_params`, `clone`, `Pipeline`, `cross_val_score`, pickling).
58
+
59
+ ## Reading the fitted model
60
+
61
+ ```python
62
+ ex = model.explain() # exact functional ANOVA (log-odds scale for a classifier)
63
+
64
+ ex.shares(X_test) # variance shares of main / pair / higher-order parts, R² of truncations
65
+ ex.importance(X_test) # spread of every main and pair effect, largest first
66
+ ex.main_effect("age") # DataFrame: value, effect (one row per level for a categorical input)
67
+ xa, xb, F = ex.pair_effect("lat", "long")
68
+ C = ex.components(X_test) # f0, main effects, pair effects, remainder, prediction per row
69
+
70
+ ex.plot_main("age"); ex.plot_pair("lat", "long"); ex.plot_shares(X_test)
71
+ ```
72
+
73
+ The decomposition is taken with respect to the product of the training marginals:
74
+ f0 = E f, f_j = E[f | x_j] − f0, f_jk = E[f | x_j, x_k] − f_j − f_k − f0, and the remainder holds the
75
+ interactions of order three and higher. At every row the parts sum to the prediction.
76
+
77
+ ## Model selection and options
78
+
79
+ By default (`selection="two_race"`, the setting of the paper) five-fold cross-validation inside the training
80
+ data chooses the additive backbone (on or off), the unit resolution (16 or 32 interior knots), the column
81
+ fraction (0.5 or 1) and support pruning (on or off). The candidates are raced on the first inner fold with
82
+ stops at 100 and 200 units, and three finalists continue on the other folds. Two races run on the same
83
+ folds, one over the eight candidates with support pruning and one over all sixteen; the winner of the second
84
+ replaces that of the first when its cross-validated loss is lower. The prediction is the average of the five
85
+ fold models. `model.selection_` reports the winning race, its candidate and the inner loss of each race.
86
+
87
+ | Parameter | Default | Meaning |
88
+ |---|---|---|
89
+ | `selection` | `"two_race"` | `"pruned"`: the first race only (about a third of the computation); `"all"`: the second only |
90
+ | `cat_features` | `"auto"` | categorical columns: `"auto"`, `None`, or a list of names / positions |
91
+ | `max_units` | 4000 | maximum number of units per fold model (early stopping decides) |
92
+ | `learning_rate` | 0.3 | shrinkage of every unit |
93
+ | `max_inputs_per_unit` | 12 | cap on the inputs a unit may use |
94
+ | `n_jobs` | 1 | processes for the inner cross-validation (the result does not depend on it) |
95
+ | `random_state` | 0 | seed of the inner folds and column draws |
96
+ | `params` | `None` | dict of further settings of the underlying `KAUnitBoost` (for experts) |
97
+
98
+ ## Results
99
+
100
+ On the 35 regression tasks of OpenML-CTR23 (ten folds, one thread per fit), MJBoost has a lower test RMSE than
101
+ EBM on 21 tasks, a statistically equal one on 12 and a higher one on 2, with a 29.1% lower geometric-mean
102
+ RMSE; against tuned LightGBM the geometric-mean RMSE is 13.2% lower. On synthetic targets of interaction
103
+ order three to six its test error is up to 13 times lower than that of EBM. On 32 binary tasks of
104
+ OpenML-CC18 its test log-loss is on par with that of EBM. Over the CTR23 run MJBoost used 130 CPU-hours,
105
+ EBM 68 and tuned LightGBM 19.
106
+
107
+ ## Citation
108
+
109
+ Minjong Cheon, Hanseon Joo and Eunji Lee. Gradient Boosting with Kolmogorov–Arnold Units for Interpretable
110
+ Regression beyond Pairwise Interactions. 2026.
111
+
112
+ ## License
113
+
114
+ MIT
@@ -0,0 +1,39 @@
1
+ """MJBoost on two data sets bundled with scikit-learn (no download)."""
2
+ import numpy as np
3
+ from sklearn.datasets import load_breast_cancer, load_diabetes
4
+ from sklearn.model_selection import train_test_split
5
+
6
+ from mjboost import MJBoostClassifier, MJBoostRegressor
7
+
8
+ # regression
9
+ X, y = load_diabetes(return_X_y=True, as_frame=True)
10
+ Xtr, Xte, ytr, yte = train_test_split(X, y, test_size=0.2, random_state=0)
11
+ reg = MJBoostRegressor().fit(Xtr, ytr)
12
+ print("diabetes test RMSE:", np.sqrt(np.mean((reg.predict(Xte) - yte) ** 2)))
13
+ print("selection:", reg.selection_["race"], reg.selection_["candidate"])
14
+
15
+ ex = reg.explain()
16
+ print(ex.shares(Xte, yte))
17
+ print(ex.importance(Xte).head(8))
18
+ print(ex.main_effect("bmi", n=9))
19
+
20
+ # binary classification
21
+ X, y = load_breast_cancer(return_X_y=True, as_frame=True)
22
+ Xtr, Xte, ytr, yte = train_test_split(X, y, test_size=0.2, random_state=0, stratify=y)
23
+ clf = MJBoostClassifier(selection="pruned").fit(Xtr, ytr)
24
+ print("breast cancer test accuracy:", np.mean(clf.predict(Xte) == yte))
25
+
26
+ try: # figures (pip install "mjboost[plot]")
27
+ import matplotlib
28
+ matplotlib.use("Agg")
29
+ import matplotlib.pyplot as plt
30
+ fig, axes = plt.subplots(1, 3, figsize=(10, 2.8))
31
+ ex.plot_main("bmi", ax=axes[0])
32
+ top = ex.importance(Xte).query("kind == 'pair'")["term"].iloc[0].split(" x ")
33
+ ex.plot_pair(top[0], top[1], ax=axes[1])
34
+ ex.plot_shares(Xte, ax=axes[2])
35
+ fig.tight_layout()
36
+ fig.savefig("mjboost_diabetes.png", dpi=150)
37
+ print("figure: mjboost_diabetes.png")
38
+ except ImportError:
39
+ pass
@@ -0,0 +1,35 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "mjboost"
7
+ version = "0.1.0"
8
+ description = "Gradient boosting with Kolmogorov-Arnold units: interpretable regression and binary classification beyond pairwise interactions, with an exact functional ANOVA of the fitted model"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{name = "Minjong Cheon"}]
13
+ requires-python = ">=3.9"
14
+ dependencies = [
15
+ "numpy>=1.22",
16
+ "scipy>=1.8",
17
+ "numba>=0.56",
18
+ "pandas>=1.4",
19
+ "scikit-learn>=1.1",
20
+ ]
21
+ keywords = ["gradient boosting", "interpretable machine learning", "generalized additive model",
22
+ "Kolmogorov-Arnold", "functional ANOVA", "tabular data"]
23
+ classifiers = [
24
+ "Programming Language :: Python :: 3",
25
+ "Operating System :: OS Independent",
26
+ "Intended Audience :: Science/Research",
27
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ plot = ["matplotlib>=3.5"]
32
+ test = ["pytest", "matplotlib>=3.5"]
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,13 @@
1
+ """MJBoost: gradient boosting with Kolmogorov-Arnold units for interpretable regression and binary
2
+ classification beyond pairwise interactions.
3
+
4
+ from mjboost import MJBoostRegressor
5
+ model = MJBoostRegressor().fit(X_train, y_train)
6
+ model.predict(X_test)
7
+ ex = model.explain() # exact functional ANOVA: main effects, pair effects, higher-order part
8
+ """
9
+ from ._estimators import MJBoostClassifier, MJBoostRegressor
10
+ from ._explain import Explanation
11
+
12
+ __version__ = "0.1.0"
13
+ __all__ = ["MJBoostRegressor", "MJBoostClassifier", "Explanation", "__version__"]