GeoLinear

Boosted piecewise-linear models on cooperative geometry partitions.

What is GeoLinear?

GeoLinear discovers cooperative geometry regimes in your data — groups of observations where features interact in similar ways — and fits an interpretable linear model inside each regime. Predictions are accumulated across boosting rounds.

The key insight is that many real-world relationships are piecewise-linear in cooperative geometry. A global linear model averages over regimes and loses the regime-specific signal. GeoLinear finds the regimes automatically (via HVRT) and lets the coefficients vary across them.

Round 1: HVRT partitions X → {cooperative, competitive, mixed} regimes
         Ridge fits within each partition on residuals
Round 2: New partitioning on updated residuals → new local Ridge models
...
Final prediction = Σ (learning_rate × stage_predictions) + intercept

Each partition's Ridge coefficients are directly interpretable as local relativities — exactly the quantities actuaries file with regulators.

Why it matters for actuaries

Insurance pricing models must be both accurate and interpretable. Regulators require filed relativities; black-box models are inadmissible. The usual compromise — vanilla GLM — leaves accuracy on the table when the true relationship is regime-switching.

GeoLinear bridges this gap:

1. Fit GeoLinear on the training portfolio. Each partition's Ridge coefficients are the relativities for that cooperative geometry segment.
2. File a meta-GLM: fit OLS(X → ŷ_GL) to compress the ensemble into a single interpretable GLM. The compression loss is typically small (R² drop < 2%).
3. Audit trail: every prediction can be traced to a specific partition and its local coefficient vector.

See examples/insurance_pricing_demo.py for a worked actuarial example including relativities tables and the GLM bridge.

Installation

pip install geolinear

Requires a C++17 compiler and CMake (automatically satisfied on most systems; the cmake PyPI package is a reliable fallback).

For the examples:

pip install geolinear[examples]   # adds xgboost, optuna, matplotlib

Quick start

Regression

from geolinear import GeoLinear
from sklearn.datasets import fetch_california_housing
from sklearn.model_selection import train_test_split
from sklearn.metrics import r2_score

X, y = fetch_california_housing(return_X_y=True)
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.2, random_state=0)

model = GeoLinear(n_rounds=20, learning_rate=0.1, alpha=1.0)
model.fit(X_tr, y_tr)
print(r2_score(y_te, model.predict(X_te)))   # ~0.72 default params

Classification

from geolinear import GeoLinearClassifier
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from sklearn.metrics import roc_auc_score

X, y = load_breast_cancer(return_X_y=True)
X_tr, X_te, y_tr, y_te = train_test_split(X, y, test_size=0.2, random_state=0)

clf = GeoLinearClassifier(n_rounds=20, alpha=1.0)
clf.fit(X_tr, y_tr)
print(roc_auc_score(y_te, clf.predict_proba(X_te)[:, 1]))  # ~0.993

Pipeline + GridSearchCV

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.model_selection import GridSearchCV
from geolinear import GeoLinear

pipe = Pipeline([("scaler", StandardScaler()), ("gl", GeoLinear())])
grid = GridSearchCV(pipe, {"gl__alpha": [0.1, 1.0, 10.0], "gl__n_rounds": [10, 20]}, cv=5)
grid.fit(X_tr, y_tr)

Optuna HPO

import optuna
from geolinear import GeoLinear
from sklearn.model_selection import cross_val_score

def objective(trial):
    model = GeoLinear(
        n_rounds=trial.suggest_int("n_rounds", 10, 100),
        learning_rate=trial.suggest_float("learning_rate", 0.01, 0.3, log=True),
        alpha=trial.suggest_float("alpha", 0.01, 20.0, log=True),
        y_weight=trial.suggest_float("y_weight", 0.1, 1.0),
        base_learner=trial.suggest_categorical("base_learner", ["ridge", "lasso"]),
        hvrt_n_partitions=trial.suggest_int("hvrt_n_partitions", 3, 14),
        min_samples_partition=trial.suggest_int("min_samples_partition", 3, 25),
        hvrt_model=trial.suggest_categorical("hvrt_model", ["hvrt", "pyramid_hart", "fast_hvrt"]),
        use_t_feature=trial.suggest_categorical("use_t_feature", [False, True]),
        refit_interval=trial.suggest_categorical("refit_interval", [0, 1, 2]),
    )
    return cross_val_score(model, X_tr, y_tr, cv=5, scoring="r2").mean()

study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=60)

Ecosystem: which tool to use?

GeoLinear is part of a family of cooperative-geometry libraries. The right choice depends on what "interpretable" means in your domain and the structure of your data.

Rule of thumb: if your regulator or ethics board requires a linear equation you can file or defend, use GeoLinear. If you need XGBoost-class accuracy with fully deterministic predictions that provide richer interpretability than SHAP, use GeoXGB. If you have repeated observations per individual and want to model how treatment effects evolve over time for each entity, use AutoITE.

Benchmark results

80-trial Optuna HPO, GeoLinear (v0.3.0) vs XGBoost. use_t_feature included in GeoLinear's HPO search space so the optimizer can exploit cooperative geometry when it exists.

Regression R² — v0.3.0 (80-trial HPO)

Score: 3 wins · 1 tie · 1 loss.

use_t_feature is selected by HPO whenever the data has cooperative structure (T-regime, 3-regime). On smooth or axis-aligned DGPs (Friedman1, Linear) HPO correctly opts out. CalHousing remains XGBoost territory: spatial autocorrelation and threshold effects are better captured by axis-aligned splits than by pairwise cooperative geometry.

Classification AUC

Default-parameter GL-Ridge matches XGBoost-HPO on BreastCancer (AUC 0.993 each).

API reference

GeoLinear (regressor)

GeoLinearClassifier accepts the same parameters.

Key methods

model.fit(X, y)                          # fit
model.predict(X)                         # regression predictions
clf.predict_proba(X)                     # class probabilities, shape (n, 2)
model.feature_importances(feature_names) # weighted mean |coef| across partitions/stages
model.stages_                            # list of (None, dict[partition_id, RidgeModel])

License

GNU Affero General Public License v3.0 or later. See LICENSE.