Metadata-Version: 2.4
Name: gdptools-pygeoapi-plugin
Version: 0.0.14
Summary: Gdptools Pygeoapi Plugin
License: LICENSE.md
License-File: LICENSE.md
Author: Richard McDonald
Author-email: rmcd@usgs.gov
Requires-Python: >=3.10,<3.13
Classifier: Development Status :: 1 - Planning
Classifier: License :: Other/Proprietary 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: Programming Language :: Python :: 3.13
Requires-Dist: distributed (>=2024.5.0)
Requires-Dist: gdptools (>=0.3.0)
Requires-Dist: geopandas (>=0.13)
Requires-Dist: pandas (>=1.5)
Requires-Dist: pyarrow (>=14.0.0)
Requires-Dist: pygeoapi (>=0.14.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)
Project-URL: Changelog, https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin/releases
Project-URL: Documentation, https://gdptools-pygeoapi-plugin.readthedocs.io
Project-URL: Homepage, https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin
Project-URL: Repository, https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin
Description-Content-Type: text/markdown

# Gdptools Pygeoapi Plugin

[![PyPI](https://img.shields.io/pypi/v/gdptools-pygeoapi-plugin.svg)](https://pypi.org/project/gdptools-pygeoapi-plugin/)
[![Status](https://img.shields.io/pypi/status/gdptools-pygeoapi-plugin.svg)](https://pypi.org/project/gdptools-pygeoapi-plugin/)
[![Python Version](https://img.shields.io/pypi/pyversions/gdptools-pygeoapi-plugin)](https://pypi.org/project/gdptools-pygeoapi-plugin)
[![License](https://img.shields.io/pypi/l/gdptools-pygeoapi-plugin)](https://creativecommons.org/publicdomain/zero/1.0/legalcode)

[![Read the documentation at https://gdptools-pygeoapi-plugin.readthedocs.io/](https://img.shields.io/readthedocs/gdptools-pygeoapi-plugin/latest.svg?label=Read%20the%20Docs)](https://gdptools-pygeoapi-plugin.readthedocs.io/)
[![Tests](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin/workflows/Tests/badge.svg)](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin/actions?workflow=Tests)
[![Codecov](https://codecov.io/gh/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin/branch/main/graph/badge.svg)](https://codecov.io/gh/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin)

[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://code.usgs.gov/pre-commit/pre-commit)
[![Ruff](https://img.shields.io/badge/linting-ruff-000000.svg?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
[![Poetry](https://img.shields.io/badge/poetry-enabled-blue)](https://python-poetry.org/)
[![Conda](https://img.shields.io/badge/conda-enabled-green)](https://anaconda.org/)

## Overview

This package provides two components for working with [gdptools](https://github.com/USGS-python/gdptools) area-weighted aggregation via [pygeoapi](https://pygeoapi.io/):

1. **Server-side Plugin** (`gdptools_pygeoapi_plugin`) - OGC API Processes for pygeoapi that expose gdptools functionality as web services
2. **Python Client** (`gdptools_pygeoapi_client`) - A lightweight Python client library for interacting with the GDP pygeoapi processes

The plugin supports two data catalog types:

- **ClimateR Catalog** - OpenDAP-based access using the [climateR-catalogs](https://github.com/mikejohnson51/climateR-catalogs) parquet file
- **NHGF STAC Catalog** - Zarr-based access using the USGS NHGF STAC API

## Features

- **Weight Calculation** - Generate grid-to-polygon intersection weights for climate data aggregation
- **Aggregation** - Run area-weighted aggregation using pre-computed weights
- **Dual Catalog Support** - Access data via ClimateR (OpenDAP) or NHGF STAC (Zarr) catalogs
- **Async Job Support** - Submit long-running jobs and poll for completion
- **Weight Caching** - Automatically cache computed weights locally to avoid redundant calculations
- **Batch Processing** - Process multiple GeoDataFrames in parallel

## Requirements

- Python 3.10 - 3.12
- pygeoapi >= 0.14.0
- gdptools > 0.2.15
- geopandas >= 0.13
- pandas >= 1.5

## Installation

You can install _Gdptools Pygeoapi Plugin_ via [pip](https://pip.pypa.io/) from [PyPI](https://pypi.org/):

```bash
pip install gdptools-pygeoapi-plugin
```

## Quick Start (Client Usage)

### Using ClimateR Catalog

```python
from gdptools_pygeoapi_client import GDPClient
import geopandas as gpd
import pandas as pd

# Load your polygons
gdf = gpd.read_file("my_watersheds.shp")

# Load a climate catalog (e.g., from climateR-catalogs)
catalog_url = "https://github.com/mikejohnson51/climateR-catalogs/releases/download/June-2024/catalog.parquet"
cat = pd.read_parquet(catalog_url)

# Build catalog dictionary for TerraClimate variables
cat_dict = {
    "aet": cat.query("id == 'terraclim' & variable == 'aet'").to_dict(orient="records")[0],
    "pet": cat.query("id == 'terraclim' & variable == 'pet'").to_dict(orient="records")[0],
}

# Initialize client (defaults to production endpoint)
client = GDPClient()

# Calculate weights using ClimateR catalog (automatically cached)
weights = client.calc_weights_climr(
    gdf=gdf,
    cat_dict=cat_dict,
    shape_crs=4326,
    shape_poly_idx="OBJECTID",
    wght_gen_proj=6931,
    start_date="1980-01-01",
    end_date="1980-12-31",
)

# Run aggregation using ClimateR catalog
results = client.calc_agg_climr(
    gdf=gdf,
    weights=weights,
    cat_dict=cat_dict,
    shape_crs=4326,
    shape_poly_idx="OBJECTID",
    start_date="1980-01-01",
    end_date="1980-12-31",
)

print(results.head())
```

### Using NHGF STAC Catalog

```python
from gdptools_pygeoapi_client import GDPClient
import geopandas as gpd

# Load your polygons
gdf = gpd.read_file("my_watersheds.shp")

# Initialize client
client = GDPClient()

# Calculate weights using NHGF STAC catalog
weights = client.calc_weights_stac(
    gdf=gdf,
    collection_id="gridmet-tmax",  # STAC collection ID
    variables=["tmax"],  # List of variables
    shape_crs=4326,
    shape_poly_idx="OBJECTID",
    wght_gen_proj=6931,
    start_date="2020-01-01",
    end_date="2020-12-31",
)

# Run aggregation using NHGF STAC catalog
results = client.calc_agg_stac(
    gdf=gdf,
    weights=weights,
    collection_id="gridmet-tmax",
    variables=["tmax"],
    shape_crs=4326,
    shape_poly_idx="OBJECTID",
    start_date="2020-01-01",
    end_date="2020-12-31",
)

print(results.head())
```

## Usage

Please see the [Usage](usage.md) section for detailed documentation on both the server plugin and client library.

## Contributing

Contributions are very welcome. To learn more, see `docs/contributing.md`.

## License

Distributed under the terms of the [CC0 1.0 Universal license](https://creativecommons.org/publicdomain/zero/1.0/legalcode), _Gdptools Pygeoapi Plugin_ is free and open source software.

## Issues

If you encounter any problems, please [file an issue](https://code.usgs.gov/wma/nhgf/toolsteam/gdptools-pygeoapi-plugin/issues) along with a detailed description.

## Credits

This project was generated from [@chill](https://code.usgs.gov/chill)'s [Pygeoapi Plugin Cookiecutter](https://code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter) template.

