Metadata-Version: 2.4
Name: geoequity
Version: 1.0.2
Summary: Spatial Equity Assessment for Machine Learning Models
Author-email: Zhehao Liang <zliang7@nd.edu>
License: MIT
Project-URL: Homepage, https://github.com/px39n/geoequity
Project-URL: Documentation, https://px39n.github.io/geoequity/
Project-URL: Repository, https://github.com/px39n/geoequity
Project-URL: Issues, https://github.com/px39n/geoequity/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.0
Requires-Dist: matplotlib>=3.4
Requires-Dist: tqdm>=4.60
Provides-Extra: full
Requires-Dist: pygam>=0.8.0; extra == "full"
Requires-Dist: xarray>=0.19; extra == "full"
Requires-Dist: geopandas>=0.10; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Dynamic: license-file

# GeoEquity

**Spatial Equity Assessment for Machine Learning Models**

[![DOI](https://zenodo.org/badge/1114901804.svg)](https://doi.org/10.5281/zenodo.17915557)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

GeoEquity diagnoses and visualizes spatial performance disparities in geospatial ML models—identifying where models underperform and predicting accuracy across space.

## Installation

```bash
pip install geoequity
```

## Quick Start

After training your ML model, use GeoEquity to analyze spatial accuracy patterns:

```python
from geoequity import TwoStageModel

# Your validated predictions (see Required Data below)
ts = TwoStageModel()
ts.fit(df_test, model_name='mymodel')

# Predict accuracy at any location
accuracy = ts.predict(longitude=5.0, latitude=50.0, density=0.001)

# Generate diagnostic report
ts.diagnose(save_dir='diagnostics/')
```

### Required Data

Your DataFrame should contain:

| Column | Description |
|--------|-------------|
| `longitude`, `latitude` | Coordinates |
| `observed` | Ground truth values |
| `predicted_{model_name}` | Your model's predictions |
| `density` | Data density at each location |
| `sufficiency` | Training sample size |

## Documentation

📖 **Full documentation**: [https://px39n.github.io/geoequity/](https://px39n.github.io/geoequity/)

- [Quick Start Guide](https://px39n.github.io/geoequity/getting-started/quickstart/)
- [Two-Stage Model](https://px39n.github.io/geoequity/guide/two-stage/)
- [Example Notebooks](https://px39n.github.io/geoequity/examples/Standard_workflow_geoequity/)

## Data

Example datasets are available on Zenodo: [https://doi.org/10.5281/zenodo.17915696](https://doi.org/10.5281/zenodo.17915696)

Direct download: [geoequity.zip](https://zenodo.org/records/17915696/files/geoequity.zip?download=1)

## Citation

```bibtex
@article{liang2025geoequity,
  title={Countering Local Overfitting for Equitable Spatiotemporal Modeling},
  author={Liang, Zhehao and Castruccio, Stefano and Crippa, Paola},
  journal={...},
  year={2025}
}
```

## License

MIT License
