API Reference

This section provides comprehensive documentation for all gdptools classes and functions.

Overview

The gdptools API is organized into several key modules:

• Data Classes: Input data handling and validation

• Weight Generation: Spatial intersection weight calculation

• Aggregation: Statistical aggregation and interpolation

• Zonal Statistics: Raster-based zonal operations

• Helper Methods: Utility functions and spatial operations

Quick Start

For most users, the primary entry points are:

# Grid-to-polygon aggregation
from gdptools import AggGen

# Polygon-to-polygon weights
from gdptools import WeightGenP2P

# Zonal statistics on rasters
from gdptools import ZonalGen

Module Index

Top-level package for pygeoapi plugin: Gdptools.

gdptools

Top-level package for pygeoapi plugin: Gdptools.

Classes and Functions Index

data.user_data.ClimRCatData(*, ...)	Interface for Climate-R catalog datasets with automatic metadata handling.
data.user_data.UserCatData(*, source_ds, ...)	Handler for user-provided xarray datasets with custom configuration.
data.user_data.NHGFStacData(*, ...[, ...])	Factory for NHGF STAC catalog datasets.
data.user_data.NHGFStacZarrData(*, ...)	Interface for Zarr-backed NHGF STAC catalog datasets.
data.user_data.NHGFStacTiffData(*, ...[, ...])	Interface for GeoTIFF-backed NHGF STAC catalog datasets (e.g., NLCD).
data.user_data.UserTiffData(source_ds, ...)	Handler for GeoTIFF and other raster data sources.
agg_gen.AggGen(user_data, stat_method, ...)	Performs grid-to-polygon aggregation using area-weighted statistics.
weight_gen.WeightGen(*, user_data, method, ...)	Calculates grid-to-polygon intersection weights for area-weighted aggregation.
weight_gen_p2p.WeightGenP2P(*, target_poly, ...)	Calculates polygon-to-polygon intersection weights for spatial data transfer.
zonal_gen.ZonalGen(user_data, zonal_engine, ...)	Calculate standard zonal statistics for raster data.
helpers.build_subset(bounds, xname, yname, ...)	Create a dictionary to use with xarray .sel() method to subset by time and space.
helpers.build_subset_tiff(bounds, xname, ...)	Create a dictionary to use with xarray .sel() method to subset TIFF data by space and band.
helpers.build_subset_tiff_da(bounds, xname, ...)	Create a dictionary to use with xarray .sel() method to subset TIFF DataArray by space.
helpers.check_gridded_data_for_dimensions(ds, ...)	Check that gridded data has the required dimensions.
data.agg_gen_data.AggData(variable, cat_cr, ...)	A container for data prepared for aggregation operations.
data.weight_gen_data.WeightData(target_gdf, ...)	A container for data prepared for weight generation.
data.odap_cat_data.CatClimRItem(*[, id, ...])	A Pydantic model for ClimateR-style catalog items.

Data Containers

gdptools passes prepared data between its stages in a few small containers. AggData and WeightData are built internally – by prep_agg_data() and prep_wght_data() respectively – and CatClimRItem models one entry of a ClimateR-style catalog. All three appear in the public API as parameter or return types, so they are documented here.

class AggData(variable, cat_cr, da, target_gdf, target_id, source_time_period)

Bases: object

A container for data prepared for aggregation operations.

This dataclass holds all the necessary data for a single variable that has been pre-processed for aggregation. This includes the original gridded data subsetted to the area of interest, the target geometries, and relevant metadata.

Instances of AggData are typically created internally by gdptools during the aggregation process. For each variable specified in a UserData object, an AggData instance is generated.

variable

Name of the data variable being processed.

Type:

str

cat_cr

Catalog metadata describing the gridded dataset.

Type:

gdptools.data.odap_cat_data.CatClimRItem

da

The gridded data, spatially and temporally subsetted to the area of interest.

Type:

xarray.DataArray

target_gdf

Target vector geometries for aggregation.

Type:

geopandas.GeoDataFrame

target_id

Column name in target_gdf that uniquely identifies each geometry.

Type:

str

source_time_period

Start and end dates for the time slice used to prepare this data.

Type:

list[str]

__init__(variable, cat_cr, da, target_gdf, target_id, source_time_period)

class WeightData(target_gdf, target_id, grid_cells)

Bases: object

A container for data prepared for weight generation.

This dataclass holds all the necessary data for calculating spatial intersection weights. This includes the target vector geometries and the source grid cell geometries.

Instances of WeightData are typically created internally by gdptools during the weight generation process.

target_gdf

The geopandas.GeoDataFrame containing the target vector geometries.

Type:

geopandas.geodataframe.GeoDataFrame

target_id

The column name in target_gdf that serves as the unique identifier for each geometry.

Type:

str

grid_cells

The geopandas.GeoDataFrame containing the source grid cell polygons.

Type:

geopandas.geodataframe.GeoDataFrame

__init__(target_gdf, target_id, grid_cells)

class CatClimRItem(*, id=None, asset=None, URL, varname, long_name=None, variable=None, description=None, units=None, model=None, ensemble=None, scenario=None, T_name=None, duration=None, interval=None, nT=0, X_name, Y_name, X1=None, Xn=None, Y1=None, Yn=None, resX, resY, ncols=None, nrows=None, proj=None, toptobottom, tiled=None, crs=None)

A Pydantic model for ClimateR-style catalog items.

This class provides a structured representation of a single entry from a climateR-style data catalog, such as the one maintained by Mike Johnson. It includes fields for dataset identification, access information (URL), variable metadata, and spatiotemporal properties.

The model includes validators to handle common data inconsistencies found in catalog files, such as converting NaN values to None, setting default values for projection, and ensuring boolean fields are correctly parsed.

Source data from: https://github.com/mikejohnson51/climateR-catalogs/releases/download/June-2024/catalog.parquet

id

Unique identifier for the dataset (e.g., ‘gridmet’).

Type:

str | None

asset

Name of the asset within the dataset.

Type:

str | None

URL

The URL to access the data, typically an OPeNDAP or HTTP endpoint.

Type:

str

varname

The specific variable name within the dataset.

Type:

str

long_name

A descriptive, human-readable name for the variable.

Type:

str | None

variable

An alternative or short name for the variable.

Type:

str | None

description

A longer description of the variable.

Type:

str | None

units

The physical units of the variable’s data.

Type:

str | None

model

The climate model that generated the data, if applicable.

Type:

str | None

ensemble

The model ensemble member, if applicable.

Type:

str | None

scenario

The climate scenario (e.g., ‘ssp245’), if applicable.

Type:

str | None

T_name

The name of the time coordinate dimension.

Type:

str | None

duration

The temporal duration of each time step (e.g., ‘1 day’).

Type:

str | None

interval

The temporal interval between time steps.

Type:

str | None

nT

The total number of time steps in the dataset.

Type:

int | None

X_name

The name of the X-coordinate (longitude) dimension.

Type:

str

Y_name

The name of the Y-coordinate (latitude) dimension.

Type:

str

X1

The minimum X-coordinate value.

Type:

float | None

Xn

The maximum X-coordinate value.

Type:

float | None

Y1

The minimum Y-coordinate value.

Type:

float | None

Yn

The maximum Y-coordinate value.

Type:

float | None

resX

The spatial resolution in the X-direction.

Type:

float

resY

The spatial resolution in the Y-direction.

Type:

float

ncols

The number of columns in the grid.

Type:

int | None

nrows

The number of rows in the grid.

Type:

int | None

proj

The projection of the dataset as a PROJ string or similar.

Type:

str | None

toptobottom

Boolean indicating if the Y-axis is oriented from top to bottom.

Type:

bool

tiled

Tiling scheme of the data, if any (e.g., ‘T’, ‘XY’).

Type:

str | None

crs

The coordinate reference system, often as an EPSG code or WKT.

Type:

str | None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

__init__(**data)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.