xcdat.bounds.BoundsAccessor#

class xcdat.bounds.BoundsAccessor(dataset)[source]#

An accessor class that provides bounds attributes and methods on xarray Datasets through the .bounds attribute.

Examples

Import BoundsAccessor class:

>>> import xcdat  # or from xcdat import bounds

Use BoundsAccessor class:

>>> ds = xcdat.open_dataset("/path/to/file")
>>>
>>> ds.bounds.<attribute>
>>> ds.bounds.<method>
>>> ds.bounds.<property>
Parameters:

dataset (xr.Dataset) – A Dataset object.

Examples

Import:

>>> from xcdat import bounds

Return dictionary of axis and coordinate keys mapped to bounds:

>>> ds.bounds.map

Return list of keys for bounds data variables:

>>> ds.bounds.keys

Add missing coordinate bounds for supported axes in the Dataset:

>>> ds = ds.bounds.add_missing_bounds()

Get coordinate bounds if they exist:

>>> lat_bounds = ds.bounds.get_bounds("Y")
>>> lon_bounds = ds.bounds.get_bounds("X")
>>> time_bounds = ds.bounds.get_bounds("T")

Add coordinate bounds for a specific axis if they don’t exist:

>>> ds = ds.bounds.add_bounds("Y")
__init__(dataset)[source]#

Methods

__init__(dataset)

add_bounds(axis[, width])

Add bounds for an axis using its coordinate points.

add_missing_bounds([width])

Adds missing coordinate bounds for supported axes in the Dataset.

get_bounds(axis[, var_key])

Gets coordinate bounds.

Attributes

keys

Returns a list of keys for the bounds data variables in the Dataset.

map

Returns a map of axis and coordinates keys to their bounds.
_dataset#
property map#

Returns a map of axis and coordinates keys to their bounds.

The dictionary provides all valid CF compliant keys for axis and coordinates. For example, latitude will includes keys for “lat”, “latitude”, and “Y”.

Returns:

Dict[str, Optional[xr.DataArray]] – Dictionary mapping axis and coordinate keys to their bounds.

property keys#

Returns a list of keys for the bounds data variables in the Dataset.

Returns:

List[str] – A list of sorted bounds data variable keys.

add_missing_bounds(width=0.5)[source]#

Adds missing coordinate bounds for supported axes in the Dataset.

This function loops through the Dataset’s axes and attempts to adds bounds to its coordinates if they don’t exist. The coordinates must meet the following criteria in order to add bounds:

  1. The axis for the coordinates are “X”, “Y”, “T”, or “Z”

  2. Coordinates are a single dimension, not multidimensional

  3. Coordinates are a length > 1 (not singleton)

  4. Bounds must not already exist. * Determined by attempting to map the coordinate variable’s “bounds” attr (if set) to the bounds data variable of the same key.

Parameters:

width (float, optional) – Width of the bounds relative to the position of the nearest points, by default 0.5.

Returns:

xr.Dataset

get_bounds(axis, var_key=None)[source]#

Gets coordinate bounds.

Parameters:

  • axis (CFAxisKey) – The CF axis key (“X”, “Y”, “T”, “Z”).

  • var_key (Optional[str]) – The key of the coordinate or data variable to get axis bounds for. This parameter is useful if you only want the single bounds DataArray related to the axis on the variable (e.g., “tas” has a “lat” dimension and you want “lat_bnds”).

Returns:

Union[xr.Dataset, xr.DataArray] – A Dataset of N bounds variables, or a single bounds variable DataArray.

Raises:

  • ValueError – If an incorrect axis argument is passed.

  • KeyError: – If bounds were not found for the specific axis.

add_bounds(axis, width=0.5)[source]#

Add bounds for an axis using its coordinate points.

This method loops over the axis’s coordinate variables and attempts to add bounds for each of them if they don’t exist. The coordinates must meet the following criteria in order to add bounds:

  1. The axis for the coordinates are “X”, “Y”, “T”, or “Z”

  2. Coordinates are single dimensional, not multidimensional

  3. Coordinates are a length > 1 (not singleton)

  4. Bounds must not already exist. * Determined by attempting to map the coordinate variable’s “bounds” attr (if set) to the bounds data variable of the same key.

Parameters:

  • axis (CFAxisKey) – The CF axis key (“X”, “Y”, “T”, or “Z”).

  • width (float, optional) – Width of the bounds relative to the position of the nearest points, by default 0.5.

Returns:

xr.Dataset – The dataset with bounds added.

Raises:

ValueError – If bounds already exist. They must be dropped first.

_get_bounds_keys(axis)[source]#

Get bounds keys for an axis’s coordinate variables in the dataset.

This function attempts to map bounds to an axis using cf_xarray and its interpretation of the CF “bounds” attribute.

Parameters:

axis (CFAxisKey) – The CF axis key (“X”, “Y”, “T”, or “Z”).

Returns:

List[str] – The axis bounds key(s).

_create_bounds(axis, coord_var, width)[source]#

Creates bounds for an axis using its coordinate points.

Parameters:

  • axis (CFAxisKey) – The CF axis key (“X”, “Y”, “T” ,”Z”).

  • coord_var (xr.DataArray) – The coordinate variable for the axis.

  • width (float) – Width of the bounds relative to the position of the nearest points.

Returns:

xr.DataArray – The axis coordinate bounds.

Raises:

ValueError – If coords dimensions does not equal 1.

Notes

Based on [1] iris.coords._guess_bounds and [2] cf_xarray.accessor.add_bounds

References

_validate_axis_arg(axis)[source]#