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.
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 (
Union[Literal[``
”generate”:class:`]`, :class:`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 ifweights
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 ifweights
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
orlon_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.
- _force_domain_order_low_to_high(domain_bounds)[source]#
Reorders the
domain_bounds
low-to-high.This method ensures all lower bound values are less than the upper bound values (
domain_bounds[:, 1] < domain_bounds[:, 1]
).- Parameters
domain_bounds (
xr.DataArray
) – The bounds of an axis.- Returns
xr.DataArray
– The bounds of an axis (re-ordered if applicable).
- _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 thebounds
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):
Align the axis orientations of the domain and region bounds to (0, 360) to ensure compatibility in the proceeding steps.
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.
Scale the domain down to a region (if selected).
Calculate weights using the domain bounds.
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.
- _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
anddata_var
. It assumes thatdata_var
has the same keys that are specified inaxis
, which has already been validated usingself._validate_axis()
inself.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 inaxis
anddata_var
, and the same axis dims sizes asdata_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
anddata_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 usingweights.fillna(0)
.