Metadata-Version: 2.4
Name: agriscope
Version: 0.1.0
Summary: Agricultural geospatial analysis toolkit
Author: Zeyad Mohamed Ali
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: geopandas
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: shapely
Requires-Dist: pyproj
Requires-Dist: fiona

# geopandas-agri

**Agricultural geospatial analysis toolkit extending GeoPandas.**

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install geopandas-agri

# With performance extras (Dask chunking support)
pip install "geopandas-agri[performance]"
```

## Quickstart

```python
import geopandas as gpd
import geopandas_agri          # registers the .agri accessor

gdf = gpd.read_file("fields.geojson")

# NDVI
gdf = gdf.agri.compute_ndvi("red", "nir")

# Soil management zones
gdf = gdf.agri.soil_zones(n_clusters=4)

# Irrigation needs
gdf = gdf.agri.irrigation_needs(evapotranspiration=5.2, rainfall=2.1)

# Summary report
print(gdf.agri.summary())
```

## CLI

```bash
# Compute NDVI
geopandas-agri compute-ndvi fields.geojson --red red --nir nir

# Soil zones
geopandas-agri soil-zones fields_ndvi.geojson --n-clusters 4

# Irrigation needs
geopandas-agri irrigation-needs fields_zones.geojson --et0 5.2 --rain 2.1

# Summary
geopandas-agri summary fields_final.geojson

# JSON output for pipeline use
geopandas-agri summary fields_final.geojson --json-output | jq .ndvi
```

## Features

| Method | Description |
|--------|-------------|
| `gdf.agri.compute_ndvi(red, nir)` | NDVI from column names or arrays |
| `gdf.agri.sample_raster(path, band)` | Sample raster at geometry locations |
| `gdf.agri.soil_zones(method, n_clusters)` | KMeans / DBSCAN / Agglomerative zoning |
| `gdf.agri.irrigation_needs(et0, rain)` | Water-balance irrigation recommendations |
| `gdf.agri.compute_ndvi_chunked(...)` | Chunked NDVI for very large datasets |
| `gdf.agri.summary()` | NDVI stats, zone distribution, irrigation counts |

## Project Structure

```
geopandas_agri/
├── __init__.py     # Package entry; registers accessor
├── accessor.py     # Thin routing layer (@pd.api.extensions accessor)
├── ndvi.py         # NDVI formula + raster sampling
├── soil.py         # Clustering-based soil zonation
├── irrigation.py   # Water-balance irrigation model
├── utils.py        # Shared validation + numeric helpers
└── cli.py          # Click CLI commands
```

## Development

```bash
git clone https://github.com/your-org/geopandas-agri
cd geopandas-agri
pip install -e ".[dev]"
pytest
```

## Roadmap / Future Extensions

1. **Crop classification** — integrate satellite time-series (Sentinel-2 / Landsat)
   with a scikit-learn or LightGBM classifier to map crop types per field.

2. **Yield prediction** — regression models (XGBoost / neural nets) trained on
   historical NDVI trajectories, soil attributes, and weather data to predict
   per-field yield before harvest.

3. **Climate data integration** — `gdf.agri.attach_era5(date_range)` to
   automatically download ERA5 reanalysis data (via `cdsapi`) and join
   precipitation, temperature, and wind speed to field geometries.

## License

MIT © 2024 Agricultural GeoData Team
