i7aof.coords

Coordinate utilities used across workflows.

Shared utilities for propagating ISMIP grid coordinates and metadata.

This module centralizes logic for:

  • Attaching standard ISMIP spatial coordinates (x, y, z/z_extrap) and their bounds, as well as geodetic coordinates (lat/lon + bounds) and CRS metadata, to output datasets.

  • Propagating time/time_bnds coordinates and their key attrs from a source dataset to a target dataset. This is useful when intermediate storage (e.g., Zarr) may alter encodings or units.

  • Selecting a dataset comprised of a target variable plus any bounds variables, while preserving coordinates.

  • Removing _FillValue encodings/attrs from coordinate variables and other auxiliary variables so that only data variables receive fill values in outputs.

These helpers are intended to be used across remapping, extrapolation, time-averaging, bias correction, TF computation, and CT/SA->thetao/so conversion workflows to ensure consistent coordinate handling.

i7aof.coords.attach_grid_coords(ds: Dataset, config: MpasConfigParser, *, z_name: str | None = None, include_lat_lon: bool = True, validate_xy: bool = True) → Dataset

Attach ISMIP grid coordinates, bounds, and CRS to a dataset.

Parameters:

  • ds (xarray.Dataset) – Target dataset to receive ISMIP spatial and geodetic coordinates.

  • config (mpas_tools.config.MpasConfigParser) – Configuration used to locate or generate the ISMIP grid via i7aof.grid.ismip.ensure_ismip_grid().

  • z_name (str, optional) – Explicit vertical coordinate to attach, usually "z" or "z_extrap". If not provided, the vertical coordinate name is inferred with vertical_name_for().

  • include_lat_lon (bool, default: True) – When True, also attach lat/lon and their bounds, plus crs if present in the grid file.

  • validate_xy (bool, default: True) – Validate that (y, x) dimensions in ds (if present) match the grid. A mismatch raises ValueError.

Returns:

A new dataset with ISMIP x/y (and bounds), the chosen vertical coordinate and bounds, geodetic coordinates (optional), and crs (when available) attached.

Return type:

xarray.Dataset

i7aof.coords.dataset_with_var_and_bounds(ds: Dataset, var_name: str) → Dataset

Return a dataset with a variable plus any present bounds variables.

Parameters:

  • ds (xarray.Dataset) – Source dataset from which to select variables.

  • var_name (str) – Name of the data variable to include.

Returns:

Subset dataset containing var_name and any of these bounds variables that exist in ds: time_bnds, x_bnds, y_bnds, z_bnds, z_extrap_bnds, lat_bnds, lon_bnds. Coordinates are preserved by xarray.

Return type:

xarray.Dataset

i7aof.coords.vertical_name_for(ds: Dataset) → str | None

Infer the preferred vertical coordinate name for a dataset.

Parameters:

ds (xarray.Dataset) – Dataset whose variables/coordinates will be inspected.

Returns:

One of "z" or "z_extrap" if present, preferring names that appear in any data variable dimensions. Returns None if neither vertical coordinate is found.

Return type:

str or None