Gdptools Pygeoapi Plugin

Overview

This package provides two components for working with gdptools area-weighted aggregation via pygeoapi:

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 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 from PyPI:

pip install gdptools-pygeoapi-plugin

Quick Start (Client Usage)

Using ClimateR Catalog

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

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 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, Gdptools Pygeoapi Plugin is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @chill's Pygeoapi Plugin Cookiecutter template.