dapper.geo package

Submodules

dapper.geo.constants module

dapper module: geo.constants.

dapper.geo.lonwrap module

dapper module: geo.lonwrap.

dapper.geo.lonwrap.infer_lon_wrap(lon_vals)

Infer whether longitudes are stored as [0, 360) or [-180, 180).

Return type:

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

Parameters:

lon_vals (ndarray)

dapper.geo.lonwrap.normalize_lon(lon, wrap)

Normalize a longitude to the requested wrapping convention.

Return type:

float

Parameters:

• lon (float)

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

dapper.geo.lonwrap.normalize_lons(lon_vals, wrap)

Vectorized longitude normalization.

Return type:

ndarray

Parameters:

• lon_vals (ndarray)

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

dapper.geo.sampling module

Point sampling and lightweight NetCDF helpers.

class dapper.geo.sampling.LatLonSpec(lat_var, lon_var, lat_dim, lon_dim, lon_wrap, lat_1d, lon_1d)

Bases: object

Minimal spec for mapping (lat, lon) -> (i, j) in a gridded dataset.

Parameters:

• lat_var (str)

• lon_var (str)

• lat_dim (str)

• lon_dim (str)

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

• lat_1d (ndarray)

• lon_1d (ndarray)

lat_1d: ndarray

lat_dim: str

lat_var: str

lon_1d: ndarray

lon_dim: str

lon_var: str

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

dapper.geo.sampling.ensure_weight(df, *, weight_col='weight', default_weight=1.0)

Ensure df has a weight column. Returns a COPY if it needs to add the column.

Return type:

DataFrame

Parameters:

• df (DataFrame)

• weight_col (str)

• default_weight (float)

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

Infer basic (regular) grid metadata for provenance.

Returns keys that are safe to stash in global attrs (namespaced with dapper). If resolution can’t be inferred reliably, values may be omitted.

Return type:

dict

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'])

dapper.geo.sampling.infer_lat_lon_vars(ds)

Prefer ELM-style 2D vars (LATIXY/LONGXY), else fall back to common names.

Return type:

tuple[str, str]

Parameters:

ds (Dataset)

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

Build a LatLonSpec for fast nearest-neighbor lookup.

Return type:

LatLonSpec

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'])

Assumptions (fine for your landuse/surf ELM-style files):

• LATIXY/LONGXY exist as 2D (lat_dim, lon_dim), OR

• lat/lon exist as 1D vectors.

dapper.geo.sampling.nearest_ij(spec, lat, lon)

Nearest-neighbor (i, j) on a regular lat/lon grid (lat_1d, lon_1d).

Return type:

tuple[int, int]

Parameters:

• spec (LatLonSpec)

• lat (float)

• lon (float)

dapper.geo.sampling.points_to_nearest_cells(ds, points, *, lat_col='lat', lon_col='lon', weight_col='weight', lat_dim='lsmlat', lon_dim='lsmlon', lat_var=None, lon_var=None, lon_wrap='auto')

Return a dataframe with (i_lat, i_lon) and the chosen cell center for each point. Keeps the original weight column.

Return type:

DataFrame

Parameters:

• ds (Dataset)

• points (DataFrame)

• lat_col (str)

• lon_col (str)

• weight_col (str)

• lat_dim (str)

• lon_dim (str)

• lat_var (str | None)

• lon_var (str | None)

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

dapper.geo.sampling.sample_gridded_dataset_points(ds, points, *, lat_col='lat', lon_col='lon', lat_dim='lsmlat', lon_dim='lsmlon', lat_var=None, lon_var=None, lon_wrap='auto', method='nearest', vars_include=None, vars_drop=None)

Sample all spatial vars (those containing BOTH lat_dim and lon_dim) at the provided point locations.

Return type:

Dataset

Parameters:

• ds (Dataset)

• points (DataFrame)

• lat_col (str)

• lon_col (str)

• lat_dim (str)

• lon_dim (str)

• lat_var (str | None)

• lon_var (str | None)

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

• method (Literal['nearest'])

• vars_include (Sequence[str] | None)

• vars_drop (Sequence[str] | None)

Output convention:

• lat_dim has length N (number of points)

• lon_dim has length 1

• no coordinate variables are created for lat_dim/lon_dim (matches your Toolik file)

dapper.geo.sampling.write_netcdf(ds, out_path, *, compress=True, complevel=4, append_attrs=None, dapper_attrs=None, add_created_utc=True)

Write a Dataset to NetCDF with optional encoding and attribute handling.

Return type:

Path

Parameters:

• ds (Dataset)

• out_path (str | Path)

• compress (bool)

• complevel (int)

• append_attrs (dict | None)

• dapper_attrs (dict | None)

• add_created_utc (bool)

dapper.geo.zonal module

Zonal (area-weighted) sampling utilities.

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

Module contents

dapper module: geo.__init__.