Metadata-Version: 2.4
Name: gimbal-regression
Version: 0.1.2
Summary: A Python package for Gimbal Regression, a deterministic local linear regression framework with explicit diagnostics.
Author: Yuichiro Otani
License: MIT License
Project-URL: Homepage, https://github.com/yuichiro-otani/grpy
Project-URL: Repository, https://github.com/yuichiro-otani/grpy
Project-URL: Issues, https://github.com/yuichiro-otani/grpy/issues
Keywords: spatial statistics,local regression,gimbal regression,anisotropy,geographically weighted regression
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Requires-Dist: geopandas>=0.14; extra == "plot"
Requires-Dist: contextily>=1.5; extra == "plot"
Provides-Extra: benchmark
Requires-Dist: statsmodels>=0.14; extra == "benchmark"
Requires-Dist: mgwr>=2.1; extra == "benchmark"
Requires-Dist: pykrige>=1.7; extra == "benchmark"
Requires-Dist: pyproj>=3.6; extra == "benchmark"
Provides-Extra: all
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: build>=1.0; extra == "all"
Requires-Dist: twine>=5.0; extra == "all"
Requires-Dist: matplotlib>=3.7; extra == "all"
Requires-Dist: geopandas>=0.14; extra == "all"
Requires-Dist: contextily>=1.5; extra == "all"
Requires-Dist: statsmodels>=0.14; extra == "all"
Requires-Dist: mgwr>=2.1; extra == "all"
Requires-Dist: pykrige>=1.7; extra == "all"
Requires-Dist: pyproj>=3.6; extra == "all"
Dynamic: license-file

# 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

```bash
pip install grpy
```

### Install from source (development mode)

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

### Optional Dependencies

Some features require additional packages.
Install as needed:

```bash
# 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

```python
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:
```bash
pip install grpy[plot]
```
Example:
```python
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)

```python
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:
```bibtex
@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
