Ctrl+K

xarray.Dataset.spatial.average

xarray.Dataset.spatial.average#

Dataset.spatial.average(data_var, axis=['X', 'Y'], weights='generate', keep_weights=False, lat_bounds=None, lon_bounds=None)#

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"]
Contents