uxarray.UxDataArray.neighborhood

UxDataArray.neighborhood(r=1.0)

Groups this data by the elements within r degrees of each grid element, to be reduced over by a method of the returned DataArrayNeighborhood.

Each reduction replaces the value at every grid element with a reduction of all elements within a circular neighborhood of radius r, as in a smoothing filter.

Parameters:

r (float, default=1.) – Radius of the neighborhood, in degrees.

Returns:

Bound to this data, so its reduction methods take only the parameters of the reduction: mean(), sum(), min(), max(), median(), ptp(), std(ddof), var(ddof), quantile(q), percentile(q), or reduce(func) for anything else. Each returns a UxDataArray of float64.

Return type:

DataArrayNeighborhood

Raises:

DataCenteringError (subclass of ValueError) – If the data is not mapped to nodes, edges, or faces.

Notes

r is a great-circle distance in degrees. An element’s neighborhood overlaps those of the elements around it, and every element is its own neighbor at distance 0, so r = 0 returns the data unchanged and the result never contains spurious NaN.

Building this queries the grid for neighbors, which usually costs more than the reduction itself. That query is what the returned object holds on to, so several reductions at one radius should share one call rather than repeat it. To share it across variables too, build the neighborhood from the grid instead, with Grid.neighborhood().

A neighborhood may span the whole grid, so the grid dimension cannot be chunked; it is collapsed to a single chunk (with a warning) for dask-backed data. The remaining dimensions stay chunked and lazy, so chunk along time rather than the grid dimension.

Examples

Apply a mean filter with a 5-degree radius:

>>> import uxarray as ux
>>> uxds = ux.tutorial.open_dataset("outCSne30-vortex")
>>> uxda = uxds["psi"]
>>> smoothed = uxda.neighborhood(r=5.0).mean()

Reductions taking a parameter receive it as a keyword argument:

>>> p90 = uxda.neighborhood(r=5.0).percentile(90)
>>> spread = uxda.neighborhood(r=5.0).std(ddof=1)

Several reductions at one radius share the neighbor query:

>>> nb = uxda.neighborhood(r=5.0)
>>> smoothed, spread = nb.mean(), nb.std()

See also

DataArrayNeighborhood

The reductions available on the returned object.

Grid.neighborhood

Neighborhood shared across several variables.

UxDataArray.topological_mean

Aggregate values across neighboring grid element types.

UxDataArray.zonal_mean

Average over latitude bands.

UxDataArray.azimuthal_mean

Average over rings of constant great-circle distance.