xcdat.spatial.SpatialAccessor

xcdat.spatial.SpatialAccessor#

class xcdat.spatial.SpatialAccessor(dataset)[source]#

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

Examples

Import SpatialAccessor class:

>>> import xcdat  # or from xcdat import spatial

Use SpatialAccessor class:

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

dataset (xr.Dataset) – A Dataset object.

__init__(dataset)[source]#

Methods

__init__(dataset)

average(data_var[, axis, weights, ...])

Calculates the spatial average for a rectilinear grid over an optionally specified regional domain.

get_weights(axis[, lat_bounds, lon_bounds, ...])

Get area weights for specified axis keys and an optional target domain.
average(data_var, axis=['X', 'Y'], weights='generate', keep_weights=False, lat_bounds=None, lon_bounds=None)[source]#

Calculates the spatial average for a rectilinear grid over an optionally specified regional domain.

Operations include:

  • If a regional boundary is specified, check to ensure it is within the data variable’s domain boundary.

  • If axis weights are not provided, get axis weights for standard axis domains specified in axis.

  • Adjust weights to conform to the specified regional boundary.

  • Compute spatial weighted average.

This method requires that the dataset’s coordinates have the ‘axis’ attribute set to the keys in axis. For example, the latitude coordinates should have its ‘axis’ attribute set to ‘Y’ (which is also CF-compliant). This ‘axis’ attribute is used to retrieve the related coordinates via cf_xarray. Refer to this method’s examples for more information.

Parameters:

  • data_var (str) – The name of the data variable inside the dataset to spatially average.

  • axis (List[SpatialAxis]) – List of axis dimensions to average over, by default [“X”, “Y”]. Valid axis keys include “X” and “Y”.

  • weights ({"generate", xr.DataArray}, optional) – If “generate”, then weights are generated. Otherwise, pass a DataArray containing the regional weights used for weighted averaging. weights must include the same spatial axis dimensions and have the same dimensional sizes as the data variable, by default “generate”.

  • keep_weights (bool, optional) – If calculating averages using weights, keep the weights in the final dataset output, by default False.

  • lat_bounds (Optional[RegionAxisBounds], optional) – A tuple of floats/ints for the regional latitude lower and upper boundaries. This arg is used when calculating axis weights, but is ignored if weights are supplied. The lower bound cannot be larger than the upper bound, by default None.

  • lon_bounds (Optional[RegionAxisBounds], optional) – A tuple of floats/ints for the regional longitude lower and upper boundaries. This arg is used when calculating axis weights, but is ignored if weights are supplied. The lower bound can be larger than the upper bound (e.g., across the prime meridian, dateline), by default None.

Returns:

xr.Dataset – Dataset with the spatially averaged variable.

Raises:

KeyError – If data variable does not exist in the Dataset.

Examples

Check the ‘axis’ attribute is set on the required coordinates:

>>> ds.lat.attrs["axis"]
>>> Y
>>>
>>> ds.lon.attrs["axis"]
>>> X

Set the ‘axis’ attribute for the required coordinates if it isn’t:

>>> ds.lat.attrs["axis"] = "Y"
>>> ds.lon.attrs["axis"] = "X"

Call spatial averaging method:

>>> ds.spatial.average(...)

Get global average time series:

>>> ts_global = ds.spatial.average("tas", axis=["X", "Y"])["tas"]

Get time series in Nino 3.4 domain:

>>> ts_n34 = ds.spatial.average("ts", axis=["X", "Y"],
>>>     lat_bounds=(-5, 5),
>>>     lon_bounds=(-170, -120))["ts"]

Get zonal mean time series:

>>> ts_zonal = ds.spatial.average("tas", axis=["X"])["tas"]

Using custom weights for averaging:

>>> # The shape of the weights must align with the data var.
>>> self.weights = xr.DataArray(
>>>     data=np.ones((4, 4)),
>>>     coords={"lat": self.ds.lat, "lon": self.ds.lon},
>>>     dims=["lat", "lon"],
>>> )
>>>
>>> ts_global = ds.spatial.average("tas", axis=["X", "Y"],
>>>     weights=weights)["tas"]
get_weights(axis, lat_bounds=None, lon_bounds=None, data_var=None)[source]#

Get area weights for specified axis keys and an optional target domain.

This method first determines the weights for an individual axis based on the difference between the upper and lower bound. For latitude the weight is determined by the difference of sine(latitude). All axis weights are then combined to form a DataArray of weights that can be used to perform a weighted (spatial) average.

If lat_bounds or lon_bounds are supplied, then grid cells outside this selected regional domain are given zero weight. Grid cells that are partially in this domain are given partial weight.

Parameters:

  • axis (List[SpatialAxis]) – List of axis dimensions to average over.

  • lat_bounds (Optional[RegionAxisBounds]) – Tuple of latitude boundaries for regional selection, by default None.

  • lon_bounds (Optional[RegionAxisBounds]) – Tuple of longitude boundaries for regional selection, by default None.

  • data_var (Optional[str]) – The key of the data variable, by default None. Pass this argument when the dataset has more than one bounds per axis (e.g., “lon” and “zlon_bnds” for the “X” axis), or you want weights for a specific data variable.

Returns:

xr.DataArray – A DataArray containing the region weights to use during averaging. weights are 1-D and correspond to the specified axes (axis) in the region.

Notes

This method was developed for rectilinear grids only. get_weights() recognizes and operate on latitude and longitude, but could be extended to work with other standard geophysical dimensions (e.g., time, depth, and pressure).

_validate_axis_arg(axis)[source]#

Validates that the axis dimension(s) exists in the dataset.

Parameters:

axis (List[SpatialAxis]) – List of axis dimensions to average over.

Raises:

  • ValueError – If a key in axis is not a supported value.

  • KeyError – If the dataset does not have coordinates for the axis dimension, or the axis attribute is not set for those coordinates.

_validate_region_bounds(axis, bounds)[source]#

Validates the bounds arg based on a set of criteria.

Parameters:

  • axis (SpatialAxis) – The axis related to the bounds.

  • bounds (RegionAxisBounds) – The axis bounds.

Raises:

  • TypeError – If bounds is not a tuple.

  • ValueError – If the bounds has 0 elements or greater than 2 elements.

  • TypeError – If the bounds lower bound is not a float or integer.

  • TypeError – If the bounds upper bound is not a float or integer.

  • ValueError – If the axis is “Y” and the bounds lower value is larger than the upper value.

_get_longitude_weights(domain_bounds, region_bounds)[source]#

Gets weights for the longitude axis.

This method performs longitudinal processing including (in order):

  1. Align the axis orientations of the domain and region bounds to (0, 360) to ensure compatibility in the proceeding steps.

  2. Handle grid cells that cross the prime meridian (e.g., [-1, 1]) by breaking such grid cells into two (e.g., [0, 1] and [359, 360]) to ensure alignment with the (0, 360) axis orientation. This results in a bounds axis of length(nlon)+1. The index of the grid cell that crosses the prime meridian is returned in order to reduce the length of weights to nlon.

  3. Scale the domain down to a region (if selected).

  4. Calculate weights using the domain bounds.

  5. If the prime meridian grid cell exists, use this cell’s index to handle the weights vector’s increased length as a result of the two additional grid cells. The extra weights are added to the prime meridian grid cell and removed from the weights vector to ensure the lengths of the weights and its corresponding domain remain in alignment.

Parameters:

  • domain_bounds (xr.DataArray) – The array of bounds for the longitude domain.

  • region_bounds (Optional[np.ndarray]) – The array of bounds for longitude regional selection.

Returns:

xr.DataArray – The longitude axis weights.

Raises:

ValueError – If the there are multiple instances in which the domain_bounds[:, 0] > domain_bounds[:, 1]

_get_latitude_weights(domain_bounds, region_bounds)[source]#

Gets weights for the latitude axis.

This method scales the domain to a region (if selected). It also scales the area between two lines of latitude as the difference of the sine of latitude bounds.

Parameters:

  • domain_bounds (xr.DataArray) – The array of bounds for the latitude domain.

  • region_bounds (Optional[np.ndarray]) – The array of bounds for latitude regional selection.

Returns:

xr.DataArray – The latitude axis weights.

_calculate_weights(domain_bounds)[source]#

Calculate weights for the domain.

This method takes the absolute difference between the upper and lower bound values to calculate weights.

Parameters:

domain_bounds (xr.DataArray) – The array of bounds for a domain.

Returns:

xr.DataArray – The weights for an axes.

_swap_lon_axis(lon, to)[source]#

Swap the longitude axis orientation.

Parameters:

  • lon (Union[xr.DataArray, np.ndarray]) – Longitude values to convert.

  • to (Literal[180, 360]) – Axis orientation to convert to, either 180 [-180, 180) or 360 [0, 360).

Returns:

Union[xr.DataArray, np.ndarray] – Converted longitude values.

Notes

This does not reorder the values in any way; it only converts the values in-place between longitude conventions [-180, 180) or [0, 360).

_scale_domain_to_region(domain_bounds, region_bounds)[source]#

Scale domain bounds to conform to a regional selection in order to calculate spatial weights.

Axis weights are determined by the difference between the upper and lower boundary. If a region is selected, the grid cell bounds outside the selected region are adjusted using this method so that the grid cell bounds match the selected region bounds. The effect of this adjustment is to give partial weight to grid cells that are partially in the selected regional domain and zero weight to grid cells outside the selected domain.

Parameters:

  • domain_bounds (xr.DataArray) – The domain’s bounds.

  • region_bounds (np.ndarray) – The region bounds that the domain bounds are scaled down to.

Returns:

xr.DataArray – Scaled dimension bounds based on regional selection.

Notes

If a lower regional selection bound exceeds the upper selection bound, this algorithm assumes that the axis is longitude and the user is specifying a region that includes the prime meridian. The lower selection bound should not exceed the upper bound for latitude.

_combine_weights(axis_weights)[source]#

Generically rescales axis weights for a given region.

This method creates an n-dimensional weighting array by performing matrix multiplication for a list of specified axis keys using a dictionary of axis weights.

Parameters:

axis_weights (AxisWeights) – Dictionary of axis weights, where key is axis and value is the corresponding DataArray of weights.

Returns:

xr.DataArray – A DataArray containing the region weights to use during averaging. weights are 1-D and correspond to the specified axis keys (axis) in the region.

_validate_weights(data_var, axis)[source]#

Validates the weights arg based on a set of criteria.

This methods checks for the dimensional alignment between the weights and data_var. It assumes that data_var has the same keys that are specified in axis, which has already been validated using self._validate_axis() in self.average().

Parameters:

  • data_var (xr.DataArray) – The data variable used for validation with user supplied weights.

  • axis (List[SpatialAxis]) – List of axes dimension(s) average over.

  • weights (xr.DataArray) – A DataArray containing the region area weights for averaging. weights must include the same spatial axis dimensions found in axis and data_var, and the same axis dims sizes as data_var.

Raises:

  • KeyError – If weights does not include the latitude dimension.

  • KeyError – If weights does not include the longitude dimension.

  • ValueError – If the axis dimension sizes between weights and data_var are misaligned.

_averager(data_var, axis)[source]#

Perform a weighted average of a data variable.

This method assumes all specified keys in axis exists in the data variable. Validation for this criteria is performed in _validate_weights().

Operations include:

  • Masked (missing) data receives zero weight.

  • Perform weighted average over user-specified axes/axis.

Parameters:

  • data_var (xr.DataArray) – Data variable inside a Dataset.

  • axis (List[SpatialAxis]) – List of axis dimensions to average over.

Returns:

xr.DataArray – Variable that has been reduced via a weighted average.

Notes

weights must be a DataArray and cannot contain missing values. Missing values are replaced with 0 using weights.fillna(0).

Contents