gimbal-regression 0.1.2

A Python package for Gimbal Regression, a deterministic local linear regression framework with explicit diagnostics.

grpy

grpy is a Python package for Gimbal Regression (GR) —
a deterministic local linear regression framework for stable and reproducible estimation under anisotropic neighborhood geometry.

The package is designed with a focus on:

• Deterministic estimation (no iterative optimization)
• Numerical stability under irregular spatial sampling
• Explicit diagnostics (conditioning, effective sample size, fallback)
• Reproducibility via a single-pass estimator

Unlike conventional local regression methods (e.g., GWR/MGWR), grpy exposes both estimates and their numerical reliability as first-class outputs.

---

Installation

Basic installation

pip install grpy

Install from source (development mode)

git clone https://github.com/yuichiro-otani/grpy.git
cd grpy
pip install -e .

Optional Dependencies

Some features require additional packages. Install as needed:

# plotting utilities
pip install grpy[plot]

# benchmarking and comparison methods
pip install grpy[benchmark]

# development tools
pip install grpy[dev]

# everything
pip install grpy[all]

Quick Example

import numpy as np
from grpy import GimbalRegression

rng = np.random.default_rng(42)
n = 100

lat = 35.0 + 0.02 * rng.random(n)
lon = 139.0 + 0.02 * rng.random(n)

x = rng.normal(size=n)
y = 1.0 + 2.0 * x + 0.1 * rng.normal(size=n)

model = GimbalRegression(
    K=20,
    h_m=2000.0,
    gamma=1.0,
)

model.fit(
    y=y,
    x=x,
    lat=lat,
    lon=lon,
)

yhat = model.predict()
diag = model.diagnostics()
summary = model.summary()

print(summary)

Map Visualization

Requires plot extras:

pip install grpy[plot]

Example:

fig, ax = model.draw_map(
    column="B1",
    title="Local coefficient B1",
    basemap=True,
)

Diagnostics

grpy returns diagnostic quantities alongside estimates:

• Condition numbers of local normal matrices
• Effective sample size (ESS)
• Fallback indicators (uniform weighting)

diag = model.diagnostics()
print(diag.head())

These diagnostics allow users to directly assess numerical reliability of local estimates, not just predictive accuracy.

Reproducibility

The estimator is:

• deterministic
• single-pass
• free from stochastic components

This ensures that results are exactly reproducible given identical inputs.

Project Structure

grpy/
├── src/grpy/
├── tests/
├── examples/

• src/grpy – core implementation
• tests/ – unit tests
• examples/ – usage examples

Citation

If you use this package, please cite:

@article{Otani2026GR,
  author  = {Otani, Yuichiro},
  title   = {Gimbal Regression: A Geometry-Aware Framework for Stable Local Linear Estimation under Anisotropic Sampling},
  journal = {arXiv preprint arXiv:2603.10382},
  year    = {2026},
  doi     = {10.48550/arXiv.2603.10382}
}

License

MIT License