Metadata-Version: 2.4
Name: geointerpo
Version: 0.2.0
Summary: Spatial interpolation toolkit — boundaries, point data, 18 methods, export, and validation
Project-URL: Repository, https://github.com/homayounrezaie/geointerpo
Author-email: Homayoun Rezaie <homayounrezaie@gmail.com>
License: MIT
Keywords: air-quality,geostatistics,idw,interpolation,kriging,spatial,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Requires-Dist: geopandas>=0.14
Requires-Dist: numpy>=1.24
Requires-Dist: pandas<2.3,>=2.0
Requires-Dist: pyproj>=3.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: scipy>=1.11
Requires-Dist: shapely>=2.0
Requires-Dist: xarray>=2023.1
Provides-Extra: data
Requires-Dist: meteostat>=1.6; extra == 'data'
Requires-Dist: openaq>=0.7; extra == 'data'
Requires-Dist: openmeteo-requests>=1.2; extra == 'data'
Requires-Dist: requests-cache>=1.1; extra == 'data'
Requires-Dist: retry-requests>=2.0; extra == 'data'
Requires-Dist: tqdm>=4.65; extra == 'data'
Provides-Extra: dem
Requires-Dist: srtm-py>=0.3.5; extra == 'dem'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: geopy>=2.4; extra == 'dev'
Requires-Dist: gstools>=1.4; extra == 'dev'
Requires-Dist: ipykernel; extra == 'dev'
Requires-Dist: jupyter; extra == 'dev'
Requires-Dist: leafmap>=0.30; extra == 'dev'
Requires-Dist: mapie>=0.6; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: meteostat>=1.6; extra == 'dev'
Requires-Dist: openaq>=0.7; extra == 'dev'
Requires-Dist: openmeteo-requests>=1.2; extra == 'dev'
Requires-Dist: plotly>=5.0; extra == 'dev'
Requires-Dist: pykrige>=1.7; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: rasterio>=1.3; extra == 'dev'
Requires-Dist: requests-cache>=1.1; extra == 'dev'
Requires-Dist: retry-requests>=2.0; extra == 'dev'
Requires-Dist: rioxarray>=0.15; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: scikit-learn>=1.3; extra == 'dev'
Requires-Dist: srtm-py>=0.3.5; extra == 'dev'
Requires-Dist: tqdm>=4.65; extra == 'dev'
Provides-Extra: era5
Requires-Dist: cdsapi>=0.7; extra == 'era5'
Provides-Extra: full
Requires-Dist: geopy>=2.4; extra == 'full'
Requires-Dist: gstools>=1.4; extra == 'full'
Requires-Dist: mapie>=0.6; extra == 'full'
Requires-Dist: matplotlib>=3.7; extra == 'full'
Requires-Dist: meteostat>=1.6; extra == 'full'
Requires-Dist: openaq>=0.7; extra == 'full'
Requires-Dist: openmeteo-requests>=1.2; extra == 'full'
Requires-Dist: plotly>=5.0; extra == 'full'
Requires-Dist: pykrige>=1.7; extra == 'full'
Requires-Dist: rasterio>=1.3; extra == 'full'
Requires-Dist: requests-cache>=1.1; extra == 'full'
Requires-Dist: retry-requests>=2.0; extra == 'full'
Requires-Dist: rioxarray>=0.15; extra == 'full'
Requires-Dist: scikit-learn>=1.3; extra == 'full'
Requires-Dist: srtm-py>=0.3.5; extra == 'full'
Requires-Dist: tqdm>=4.65; extra == 'full'
Provides-Extra: geo
Requires-Dist: geopy>=2.4; extra == 'geo'
Provides-Extra: geostat
Requires-Dist: gstools>=1.4; extra == 'geostat'
Provides-Extra: interactive
Requires-Dist: plotly>=5.0; extra == 'interactive'
Provides-Extra: kriging
Requires-Dist: pykrige>=1.7; extra == 'kriging'
Requires-Dist: scikit-learn>=1.3; extra == 'kriging'
Provides-Extra: notebooks
Requires-Dist: geemap>=0.30; extra == 'notebooks'
Requires-Dist: ipykernel; extra == 'notebooks'
Requires-Dist: jupyter; extra == 'notebooks'
Requires-Dist: leafmap>=0.30; extra == 'notebooks'
Requires-Dist: matplotlib>=3.7; extra == 'notebooks'
Requires-Dist: nbformat; extra == 'notebooks'
Requires-Dist: plotly>=5.0; extra == 'notebooks'
Provides-Extra: raster
Requires-Dist: rasterio>=1.3; extra == 'raster'
Requires-Dist: rioxarray>=0.15; extra == 'raster'
Provides-Extra: uncertainty
Requires-Dist: mapie>=0.6; extra == 'uncertainty'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == 'viz'
Description-Content-Type: text/markdown

# geointerpo

<p align="center">
  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=flat-square"/>
  <img src="https://img.shields.io/badge/methods-18-teal?style=flat-square"/>
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square"/>
  <img src="https://img.shields.io/badge/docs-online-orange?style=flat-square"/>
</p>

<p align="center">
  Spatial interpolation for Python — 18 methods, live data APIs, and boundary clipping.<br/>
  Drop in point data, get a smooth interpolated raster out.<br/><br/>
  Fetch live weather, air quality, or precipitation data from <b>Meteostat</b>, <b>OpenAQ</b>, <b>Open-Meteo</b>, <b>NASA POWER</b>, and <b>ERA5</b>.<br/>
  Define your study area by place name, polygon file, or bounding box — boundaries are resolved automatically.<br/>
  Export to <b>GeoTIFF</b> or <b>NetCDF</b>, run spatial cross-validation, compare methods side by side, and visualize interactively.
</p>

<p align="center">
  <a href="https://homayounrezaie.github.io/geointerpo"><b>📖 Documentation</b></a> ·
  <a href="https://homayounrezaie.github.io/geointerpo/install/">Install</a> ·
  <a href="https://homayounrezaie.github.io/geointerpo/quickstart/">Quickstart</a> ·
  <a href="https://homayounrezaie.github.io/geointerpo/interpolators/">Methods</a> ·
  <a href="https://homayounrezaie.github.io/geointerpo/examples/">Examples</a>
</p>

---

<p align="center">
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/kriging.png" width="270"/>
  &nbsp;&nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/natural_neighbor.png" width="270"/>
  &nbsp;&nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/gp.png" width="270"/>
</p>
<p align="center"><i>Ordinary Kriging · Natural Neighbor · Gaussian Process — same 60 stations, Alberta, Canada</i></p>

---

## Install

```bash
pip install "geointerpo[full]"
```

## Quickstart

```python
from geointerpo import Pipeline

result = Pipeline(
    data="stations.csv",               # CSV, GeoDataFrame, or live API
    boundary="Calgary, Alberta",       # place name, bbox, or polygon file
    method=["idw", "kriging", "spline"],
).run()

result.plot()            # side-by-side comparison
result.plot_interactive()# zoomable plotly/leafmap map
result.metrics_table()   # cross-validation RMSE / r
result.best_method()     # best CV score
result.save("outputs/")  # GeoTIFF + PNG + CSV
```

---

## Methods

geointerpo covers 18 canonical methods across deterministic, geostatistical, and ML workflows. All share the same interface — swap `method=` to compare.

### Distance-based

The fastest methods — no statistical assumptions, exact at data points. Ideal as a quick baseline or when data is dense and evenly distributed.

<p align="center">
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/idw.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/nearest.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/linear.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/cubic.png" width="220"/>
</p>

`idw` · `nearest` · `linear` · `cubic`

### Spline & Trend

Fit smooth continuous surfaces. Splines minimise curvature; RBF offers eight kernel choices; Trend fits a global polynomial for large-scale patterns.

<p align="center">
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/spline.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/spline_tension.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/rbf.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/trend.png" width="220"/>
</p>

`spline` · `spline_tension` · `rbf` · `trend`

### Geostatistical

Account for spatial autocorrelation via a variogram model. Produce statistically optimal, unbiased estimates. Natural Neighbor uses Voronoi area-stealing weights — smooth and exact at data locations.

<p align="center">
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/kriging.png" width="290"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/uk.png" width="290"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/natural_neighbor.png" width="290"/>
</p>

`kriging` (Ordinary) · `uk` (Universal) · `natural_neighbor`

### Machine Learning

Capture non-linear spatial patterns. GP returns a full uncertainty surface alongside the mean prediction. Regression Kriging combines an ML trend with Kriging of the residuals.

<p align="center">
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/gp.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/rf.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/gbm.png" width="220"/>
  &nbsp;
  <img src="https://raw.githubusercontent.com/homayounrezaie/geointerpo/main/outputs/methods/rk.png" width="220"/>
</p>

`gp` (Gaussian Process) · `rf` (Random Forest) · `gbm` (Gradient Boosting) · `rk` (Regression Kriging)

---

## References

- [ArcGIS Pro — Interpolation Tools Overview](https://pro.arcgis.com/en/pro-app/latest/tool-reference/spatial-analyst/an-overview-of-the-interpolation-tools.htm)
- [3 Best Methods for Spatial Interpolation — Towards Data Science](https://towardsdatascience.com/3-best-methods-for-spatial-interpolation-912cab7aee47/)
- [GeoStat-Framework/PyKrige](https://github.com/GeoStat-Framework/PyKrige) — Ordinary, Universal, and Regression Kriging
- [GeoStat-Framework/GSTools](https://github.com/GeoStat-Framework/GSTools) — Covariance models, variograms, random fields
- [mmaelicke/scikit-gstat](https://github.com/mmaelicke/scikit-gstat) — Variogram estimation and ordinary kriging
- [DataverseLabs/pyinterpolate](https://github.com/DataverseLabs/pyinterpolate) — IDW, kriging, Poisson kriging
- [fatiando/verde](https://github.com/fatiando/verde) — Machine-learning-style spatial gridding
- [GeostatsGuy/GeostatsPy](https://github.com/GeostatsGuy/GeostatsPy) — GSLIB-based geostatistics
