easyclimate.filter.smooth¶

Spatial smoothing

Functions¶

`calc_spatial_smooth_gaussian`(...)	Filter with normal distribution of weights.
`calc_spatial_smooth_rectangular`(...)	Filter with a rectangular window smoother.
`calc_spatial_smooth_5or9_point`(...)	Filter with an 5-point or 9-point smoother.
`calc_forward_smooth`(→ xarray.DataArray \| xarray.Dataset)	Filter with the forward smooth.
`calc_reverse_smooth`(→ xarray.DataArray \| xarray.Dataset)	Filter with the reverse smooth.
`calc_spatial_smooth_circular`(...)	Filter with a circular window smoother.
`calc_spatial_smooth_window`(...)	Filter with an arbitrary window smoother.

Module Contents¶

easyclimate.filter.smooth.calc_spatial_smooth_gaussian(data: xarray.DataArray | xarray.Dataset, n: int = 3, lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray | xarray.Dataset¶

Filter with normal distribution of weights.

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
n: int.: Degree of filtering.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

easyclimate.filter.smooth.calc_spatial_smooth_rectangular(data: xarray.DataArray | xarray.Dataset, rectangle_shapes: int | Sequence[int] = 3, times: int = 1, lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray | xarray.Dataset¶

Filter with a rectangular window smoother.

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
rectangle_shapes: int or Sequence[int], default 3.: Shape of rectangle along the trailing dimension(s) of the data.
times: int or , default 1.: The number of times to apply the filter to the data.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

easyclimate.filter.smooth.calc_spatial_smooth_5or9_point(data: xarray.DataArray | xarray.Dataset, n: {5, 9} = 5, times: int = 1, lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray | xarray.Dataset¶

Filter with an 5-point or 9-point smoother.

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
n: {5, 9}, default 5.: The number of points to use in smoothing, only valid inputs are 5 and 9.
times: int or , default 1.: The number of times to apply the filter to the data.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

easyclimate.filter.smooth.calc_forward_smooth(data: xarray.DataArray | xarray.Dataset, n: int = 5, S: float = 0.5, times: int = 1, normalize_weights=False, lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray | xarray.Dataset¶

Filter with the forward smooth.

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
n: {5, 9}, default 5.: The number of points to use in smoothing, only valid inputs are 5 and 9.
S: float, default 0.5.: The smoothing factor.
times: int, default 1.: The number of times to apply the filter to the data.
normalize_weights: bool, default False.: If True, divide the values in window by the sum of all values in the window to obtain the normalized smoothing weights. If False, use supplied values directly as the weights.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

Note

For any discrete variable, its value on the \(x\)-axis can be described as \(F_i = F(x_i)\), where \(x_i = i \Delta x, i = 0, \pm 1, \pm 2\).

Define a one-dimensional smoothing operator

\[\overset{\sim}{F}_{i}^x = (1-S)F_i + \frac{S}{2} (F_{i+1} + F_{i-1})\]

Here, \(S\) is the spatial smoothing coefficient. Since the above formula only involves the values of three grid data points (\(F_i, F_{i+1}, F_{i-1}\)), it is also referred to as a three-point smoothing.

Correspondingly, for a two-dimensional variable \(F_{i,j}\), smoothing is performed in the \(x\) direction as follows

\[\overset{\sim}{F}_{i,j}^x = F_{i,j} + \frac{S}{2} (F_{i+1,j} + F_{i-1,j}-2F_{i,j})\]

And, smoothing is done in the \(y\) direction separately

\[\overset{\sim}{F}_{i,j}^y = F_{i,j} + \frac{S}{2} (F_{i,j+1} + F_{i,j-1}-2F_{i,j})\]

Taking the average of both results:

\[\overset{\sim}{F}_{i,j}^{x,y} = \frac{\overset{\sim}{F}_{i,j}^x + \overset{\sim}{F}_{i,j}^y}{2} = F_{i,j} + \frac{S}{4}(F_{i+1,j}+F_{i,j+1}+F_{i-1,j}+F_{i,j-1}-4F_{i,j})\]

At this point, the following “window” matrix \(\mathbf{W}\) can be obtained

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} F_{i-1,j+1} & F_{i,j+1} & F_{i+1,j+1} \\ F_{i-1,j} & F_{i,j} & F_{i+1,j} \\ F_{i-1,j-1} & F_{i,j-1} & F_{i+1,j-1} \end{array} \right) = \left( \begin{array}{ccc} 0 & \frac{S}{4} & 0 \\ \frac{S}{4} & (1-S) & \frac{S}{4} \\ 0 & \frac{S}{4} & 0 \end{array} \right)\end{split}\]

When \(S=0.5\), we have

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} 0 & 0.125 & 0 \\ 0.125 & 0.5 & 0.125 \\ 0 & 0.125 & 0 \end{array} \right)\end{split}\]

This is the “window” matrix used by the function when \(n=5\).

For the variable \(F_{i,j}\), applying a three-point smoothing in the \(x\)-axis direction followed by a three-point smoothing in the \(y\)-axis direction results in the following nine-point smoothing scheme

\[\overset{\sim}{F}_{i,j}^{x,y} = {F}_{i,j} + \frac{S}{2}(1-S)(F_{i+1,j}+F_{i,j+1}+F_{i-1,j}+F_{i,j-1}-4F_{i,j})+\frac{S^2}{4}(F_{i+1,j+1}+F_{i-1,j+1}+F_{i-1,j-1}+F_{i+1,j-1}-4F_{i,j})\]

At this point, the corresponding “window” matrix \(\mathbf{W}\) is given by

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} F_{i-1,j+1} & F_{i,j+1} & F_{i+1,j+1} \\ F_{i-1,j} & F_{i,j} & F_{i+1,j} \\ F_{i-1,j-1} & F_{i,j-1} & F_{i+1,j-1} \end{array} \right) = \left( \begin{array}{ccc} \frac{S^2}{4} & \frac{S}{2}(1-S) & \frac{S^2}{4} \\ \frac{S}{2}(1-S) & 1-2S(1-S) & \frac{S}{2}(1-S) \\ \frac{S^2}{4} & \frac{S}{2}(1-S) & \frac{S^2}{4} \end{array} \right)\end{split}\]

When \(S=0.5\), we have

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} 0.0625 & 0.125 & 0.0625 \\ 0.125 & 0.5 & 0.125 \\ 0.0625 & 0.125 & 0.0625 \end{array} \right)\end{split}\]

This is the “window” matrix used by the function when \(n=9\).

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
n: {5, 9}, default 5.: The number of points to use in smoothing, only valid inputs are 5 and 9.
S: float, default -0.5.: The smoothing factor.
times: int, default 1.: The number of times to apply the filter to the data.
normalize_weights: bool, default False.: If True, divide the values in window by the sum of all values in the window to obtain the normalized smoothing weights. If False, use supplied values directly as the weights.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

Note

For any discrete variable, its value on the \(x\)-axis can be described as \(F_i = F(x_i)\), where \(x_i = i \Delta x, i = 0, \pm 1, \pm 2\).

Define a one-dimensional smoothing operator

\[\overset{\sim}{F}_{i}^x = (1-S)F_i + \frac{S}{2} (F_{i+1} + F_{i-1})\]

Correspondingly, for a two-dimensional variable \(F_{i,j}\), smoothing is performed in the \(x\) direction as follows

\[\overset{\sim}{F}_{i,j}^x = F_{i,j} + \frac{S}{2} (F_{i+1,j} + F_{i-1,j}-2F_{i,j})\]

And, smoothing is done in the \(y\) direction separately

\[\overset{\sim}{F}_{i,j}^y = F_{i,j} + \frac{S}{2} (F_{i,j+1} + F_{i,j-1}-2F_{i,j})\]

Taking the average of both results:

\[\overset{\sim}{F}_{i,j}^{x,y} = \frac{\overset{\sim}{F}_{i,j}^x + \overset{\sim}{F}_{i,j}^y}{2} = F_{i,j} + \frac{S}{4}(F_{i+1,j}+F_{i,j+1}+F_{i-1,j}+F_{i,j-1}-4F_{i,j})\]

At this point, the following “window” matrix \(\mathbf{W}\) can be obtained

When \(S=0.5\), we have

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} 0 & 0.125 & 0 \\ 0.125 & 0.5 & 0.125 \\ 0 & 0.125 & 0 \end{array} \right)\end{split}\]

This is the “window” matrix used by the function when \(n=5\).

\[\overset{\sim}{F}_{i,j}^{x,y} = {F}_{i,j} + \frac{S}{2}(1-S)(F_{i+1,j}+F_{i,j+1}+F_{i-1,j}+F_{i,j-1}-4F_{i,j})+\frac{S^2}{4}(F_{i+1,j+1}+F_{i-1,j+1}+F_{i-1,j-1}+F_{i+1,j-1}-4F_{i,j})\]

At this point, the corresponding “window” matrix \(\mathbf{W}\) is given by

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} F_{i-1,j+1} & F_{i,j+1} & F_{i+1,j+1} \\ F_{i-1,j} & F_{i,j} & F_{i+1,j} \\ F_{i-1,j-1} & F_{i,j-1} & F_{i+1,j-1} \end{array} \right) = \left( \begin{array}{ccc} \frac{S^2}{4} & \frac{S}{2}(1-S) & \frac{S^2}{4} \\ \frac{S}{2}(1-S) & 1-2S(1-S) & \frac{S}{2}(1-S) \\ \frac{S^2}{4} & \frac{S}{2}(1-S) & \frac{S^2}{4} \end{array} \right)\end{split}\]

When \(S=0.5\), we have

\[\begin{split}\mathbf{W} = \left( \begin{array}{ccc} 0.0625 & 0.125 & 0.0625 \\ 0.125 & 0.5 & 0.125 \\ 0.0625 & 0.125 & 0.0625 \end{array} \right)\end{split}\]

This is the “window” matrix used by the function when \(n=9\).

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
radius: int.: Radius of the circular smoothing window. The “diameter” of the circle (width of smoothing window) is \(2 \cdot \mathrm{radius} + 1\) to provide a smoothing window with odd shape.
times: int, default 1.: The number of times to apply the filter to the data.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).

easyclimate.filter.smooth.calc_spatial_smooth_window(data: xarray.DataArray | xarray.Dataset, window: numpy.ndarray | xarray.DataArray, times: int = 1, normalize_weights: bool = False, lon_dim: str = 'lon', lat_dim: str = 'lat') → xarray.DataArray | xarray.Dataset¶

Filter with an arbitrary window smoother.

Parameters¶

data: xarray.DataArray or xarray.Dataset.: Some n-dimensional latitude-longitude dataset.
windownumpy.ndarray or xarray.DataArray.: Window to use in smoothing. Can have dimension less than or equal to \(N\). If dimension less than \(N\), the scalar grid will be smoothed along its trailing dimensions. Shape along each dimension must be odd.
times: int, default 1.: The number of times to apply the filter to the data.
normalize_weights: bool, default False.: If True, divide the values in window by the sum of all values in the window to obtain the normalized smoothing weights. If False, use supplied values directly as the weights.
lon_dim: str, default: lon.: Longitude coordinate dimension name. By default extracting is applied over the lon dimension.
lat_dim: str, default: lat.: Latitude coordinate dimension name. By default extracting is applied over the lat dimension.

Returns¶

The filtered latitude-longitude dataset (xarray.DataArray or xarray.Dataset).