dapper.geo.zonal

Zonal (area-weighted) sampling utilities.

Functions

infer_rectilinear_grid(ds, *[, lat_dim, ...])	Infer a rectilinear grid specification (bounds and lon wrap) from a Dataset.
intersect_weights_rectilinear(ds, targets, *)	Compute area-weighted intersections between target polygons and a rectilinear grid.
laea_crs_for_targets(targets_wgs84)	One equal-area CRS for the whole domain (LAEA centered on centroid).
normalize_geometry_lon(geom, wrap)	Apply the same lon wrap convention as sampling.normalize_lon to all coords.
reduce_wmode(da_sel, w, *[, cell_dim, tie_break])	Reduce da_sel over cell_dim using an area-weighted mode.
sample_gridded_dataset_polygons(ds, targets, *)	Zonal-sample spatial vars (those with BOTH lat_dim and lon_dim) onto target polygons.

Classes

RectilinearGrid(lat_dim, lon_dim, lon_wrap, ...)	Lightweight description of a rectilinear lat/lon grid in a consistent lon wrap.
ZonalWeights(by_gid, lon_wrap, equal_area_crs)	Zonal intersection weights grouped by feature id.

class dapper.geo.zonal.RectilinearGrid(lat_dim, lon_dim, lon_wrap, lat_bnds, lon_bnds)

Bases: object

Lightweight description of a rectilinear lat/lon grid in a consistent lon wrap.

Parameters:

• lat_dim (str)

• lon_dim (str)

• lon_wrap (Literal['0_360', '-180_180'])

• lat_bnds (ndarray)

• lon_bnds (ndarray)

lat_bnds: ndarray

lat_dim: str

lon_bnds: ndarray

lon_dim: str

lon_wrap: Literal['0_360', '-180_180']

property nlat: int

Number of latitude cells.

property nlon: int

Number of longitude cells.

class dapper.geo.zonal.ZonalWeights(by_gid, lon_wrap, equal_area_crs)

Bases: object

Zonal intersection weights grouped by feature id.

• by_gid[gid] is a pandas DataFrame with columns: i_lat, i_lon, intersect_area_m2, weight.

• weight is normalized to sum to 1 for that gid.

Parameters:

• by_gid (dict[str, DataFrame])

• lon_wrap (Literal['0_360', '-180_180'])

• equal_area_crs (str)

by_gid: dict[str, DataFrame]

equal_area_crs: str

lon_wrap: Literal['0_360', '-180_180']

dapper.geo.zonal.infer_rectilinear_grid(ds, *, lat_dim='lsmlat', lon_dim='lsmlon', lat_var=None, lon_var=None, lon_wrap='auto')

Infer a rectilinear grid specification (bounds and lon wrap) from a Dataset.

Return type:

RectilinearGrid

Parameters:

• ds (Dataset)

• lat_dim (str)

• lon_dim (str)

• lat_var (str | None)

• lon_var (str | None)

• lon_wrap (Literal['auto', '0_360', '-180_180'])

Preference order:

1. For rectilinear grids, use 1D coordinate vectors on (lat_dim, lon_dim) if present, unless the caller explicitly provides lat_var/lon_var.

2. Otherwise fall back to sampling.infer_latlon_spec (e.g., LATIXY/LONGXY or provided vars).

dapper.geo.zonal.intersect_weights_rectilinear(ds, targets, *, lat_dim='lsmlat', lon_dim='lsmlon', lat_var=None, lon_var=None, lon_wrap='auto', min_frac=0.0)

Compute area-weighted intersections between target polygons and a rectilinear grid.

Return type:

ZonalWeights

Parameters:

• ds (Dataset)

• targets (geopandas.GeoDataFrame)

• lat_dim (str)

• lon_dim (str)

• lat_var (str | None)

• lon_var (str | None)

• lon_wrap (Literal['auto', '0_360', '-180_180'])

• min_frac (float)

dapper.geo.zonal.laea_crs_for_targets(targets_wgs84)

One equal-area CRS for the whole domain (LAEA centered on centroid). Returns PROJ string usable by GeoPandas.

Return type:

str

Parameters:

targets_wgs84 (geopandas.GeoDataFrame)

dapper.geo.zonal.normalize_geometry_lon(geom, wrap)

Apply the same lon wrap convention as sampling.normalize_lon to all coords. This is the simplest way to make target polygons comparable to source grid.

Parameters:

wrap (Literal['0_360', '-180_180'])

dapper.geo.zonal.reduce_wmode(da_sel, w, *, cell_dim='cell', tie_break='smallest')

Reduce da_sel over cell_dim using an area-weighted mode.

da_sel: DataArray with dimension cell_dim and any number of other dims. w: 1D weights over cell_dim (normalized or not; only relative weights matter).

Return type:

DataArray

Parameters:

• da_sel (DataArray)

• w (DataArray)

• cell_dim (str)

• tie_break (Literal['smallest', 'largest', 'first'])

dapper.geo.zonal.sample_gridded_dataset_polygons(ds, targets, *, lat_dim='lsmlat', lon_dim='lsmlon', lat_var=None, lon_var=None, lon_wrap='auto', vars_include=None, vars_drop=None, agg_policy=None, default_float='wmean', default_int='wmode', weights=None)

Zonal-sample spatial vars (those with BOTH lat_dim and lon_dim) onto target polygons.

Return type:

Dataset

Parameters:

• ds (Dataset)

• targets (geopandas.GeoDataFrame)

• lat_dim (str)

• lon_dim (str)

• lat_var (str | None)

• lon_var (str | None)

• lon_wrap (Literal['auto', '0_360', '-180_180'])

• vars_include (Sequence[str] | None)

• vars_drop (Sequence[str] | None)

• agg_policy (dict[str, str] | None)

• default_float (str)

• default_int (str)

• weights (ZonalWeights | None)

Output convention matches sample_gridded_dataset_points:

• lat_dim has length N (number of targets, in targets row order)

• lon_dim has length 1

• no coordinate variables are created for lat_dim/lon_dim