erlab.analysis.transform¶

Transformations.

Functions

`rotate`(darr, angle[, axes, center, reshape, ...])	Rotate an array in the plane defined by the two axes.
`rotateinplane`(data, rotate, **interp_kwargs)	Rotate a 2D DataArray in the plane defined by the two dimensions.
`rotatestackinplane`(data, rotate, **interp_kwargs)	Rotate a 3D DataArray in the plane defined by the two dimensions.
`shift`(darr, shift, along, *[, shift_coords, ...])	Shifts the values of a DataArray along a single dimension.
`symmetrize`(darr, dim, *[, center, subtract, ...])	Symmetrize a DataArray along a specified dimension around a given center.
`symmetrize_nfold`(darr, fold[, axes, center, ...])	Symmetrize a plane by averaging equally spaced rotations.

erlab.analysis.transform.rotate(darr, angle, axes=(0, 1), center=(0.0, 0.0), *, reshape=True, order=1, mode='constant', cval=nan, prefilter=True)[source]¶

Rotate an array in the plane defined by the two axes.

Parameters:

darr (DataArray) – The array to rotate. The coordinates along both rotation axes must be evenly spaced and contain at least two points.
angle (float) – The rotation angle in degrees.
axes (tuple of 2 ints or 2 strings, optional) – The two axes that define the plane of rotation. Default is the first two axes. If strings are provided, they must be valid dimension names in the input array.
center (tuple of 2 floats or dict, optional) – The center of rotation in data coordinates. If a tuple, it is given as values along the dimensions specified in axes. If a dict, it must have keys that correspond exactly to axes. Default is (0, 0).
reshape (bool, default: True) – If True, the output shape is adapted to the full rotated bounding box. The extent depends on the input coordinates, not on finite data values. Default is True.
order (int, default: 1) – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.
mode (str, default: 'constant') – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.
cval (float, default: nan) – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.
prefilter (bool, default: True) – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.

Returns:

rotated (xarray.DataArray) – A new array with the same dimension names and order as darr. If reshape is True, the two rotation-axis coordinates and sizes are replaced by the full rotated bounding box at the original coordinate spacing. If False, the original grid is retained. Non-dimension coordinates that depend on either rotation axis are dropped because they no longer describe the transformed data. Other coordinates, the data name, attributes, dtype, and Dask-backed execution are preserved.

Return type:

DataArray

See also

scipy.ndimage.affine_transform: The function that performs the affine transformation on the input array.
scipy.ndimage.rotate: Similar function that rotates a numpy array.

erlab.analysis.transform.rotateinplane(data, rotate, **interp_kwargs)[source]¶

Rotate a 2D DataArray in the plane defined by the two dimensions.

Deprecated since version 2.9.0: Use erlab.analysis.transform.rotate() instead.

erlab.analysis.transform.rotatestackinplane(data, rotate, **interp_kwargs)[source]¶

Rotate a 3D DataArray in the plane defined by the two dimensions.

Deprecated since version 2.9.0: Use erlab.analysis.transform.rotate() instead.

erlab.analysis.transform.shift(darr, shift, along, *, shift_coords=False, keep_dim_order=True, assume_sorted=False, **shift_kwargs)[source]¶

Shifts the values of a DataArray along a single dimension.

The shift is applied using scipy.ndimage.shift(), which uses spline interpolation. By default, the spline is of order 1 (linear interpolation).

Parameters:

darr (DataArray) – The array to shift.
shift (float | DataArray) – The shift in the coordinate units of along. Positive values move data toward increasing coordinate values. If shift is a DataArray, different shifts can be applied to different coordinates. The dimensions of shift must be a subset of the dimensions of darr. For more information, see the note below. If shift is a float, the same shift is applied to all values along dimension along. This is equivalent to providing a 0-dimensional DataArray.
along (str) – Name of the dimension along which the shift is applied.
shift_coords (bool, default: False) – If True, the coordinates of the output data will be changed so that the output contains all the values of the original data. If False, the coordinates and shape of the original data will be retained, and only the data will be shifted. Defaults to False.
keep_dim_order (bool, default: True) – If True, the output array will be transposed to match the input data. Otherwise, the axis order may change due to the application of xarray.apply_ufunc(). Default is True.
assume_sorted (bool, default: False) – If False, the data is sorted with respect to along using xarray.DataArray.sortby(). Providing True skips the sort. Use True when you are already sure that the data is sorted ascending with respect to along.
**shift_kwargs – Additional keyword arguments passed onto scipy.ndimage.shift. The default values of some parameters are different from scipy. order is set to 1, cval is set to np.nan, and prefilter is set to False.

Returns:

shifted (xarray.DataArray) – A new shifted array. By default, the coordinate along along is sorted in ascending order and the input dimension order, data name, and attributes are retained. If shift_coords is False, the coordinate values and shape are retained. If True, the coordinate is shifted and padded to contain the moved data, so the size of along can increase.

Return type:

DataArray

Note

All dimensions in shift must be a dimension in darr.
The shift array values are divided by the step size along the along dimension.
NaN values in shift are treated as zero.

Example

>>> import xarray as xr
>>> import numpy as np
>>> import erlab.analysis as era
>>> darr = xr.DataArray(
...     np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]).astype(float), dims=["x", "y"]
... )
>>> shift_arr = xr.DataArray([1, 0, 2], dims=["x"])
>>> shifted = era.transform.shift(darr, shift_arr, along="y")
>>> print(shifted)
<xarray.DataArray (x: 3, y: 3)> Size: 72B
array([[nan,  1.,  2.],
       [ 4.,  5.,  6.],
       [nan, nan,  7.]])
Dimensions without coordinates: x, y

erlab.analysis.transform.symmetrize(darr, dim, *, center=0.0, subtract=False, average=False, mode='full', part='both', interp_kw=None)[source]¶

Symmetrize a DataArray along a specified dimension around a given center.

This function takes an input DataArray and symmetrizes its values along the specified dimension by reflecting and combining the data in regions below and above a given center.

The operation assumes that the coordinate corresponding to the dimension is evenly spaced. Internally, the function interpolates the data to a shifted coordinate grid to align with the nearest grid point, performs the reflection, and concatenates the resulting halves.

Parameters:

darr (DataArray) – The input xarray DataArray to be symmetrized. Its coordinate along the specified dimension must be uniformly spaced.
dim (Hashable) – The dimension along which to perform the symmetrization.
center (float, optional) – The central value about which the data is symmetrized (default is 0.0).
subtract (bool, optional) – If True, the reflected part is subtracted from the original data instead of being added, resulting in an antisymmetrized output instead of a symmetrized one. Default is False (i.e., the reflected part is added).
average (bool, optional) – If True, divide the summed or subtracted values by 2 where the original and reflected coordinate ranges overlap. Values outside the overlapping region remain unchanged when mode="full". Default is False.
mode ({'valid', 'full'}, optional) – How to handle the parts of the symmetrized data that does not overlap with the original data. If ‘valid’, only the part that exists in both the original and reflected data is returned. If ‘full’, the full symmetrized data is returned. In this case, all NaN values in the part that exists in the overlapping region are replaced with 0.0.
part ({'both', 'below', 'above'}, optional) – The part of the symmetrized data to return. If ‘both’, the full symmetrized data is returned. If ‘below’, only the part below the center is returned. If ‘above’, only the part above the center is returned.
interp_kw (dict, optional) – Additional keyword arguments passed to xarray.DataArray.interp().

Returns:

symmetrized (xarray.DataArray) – A new array containing the sum or difference of each value and its reflected counterpart, optionally divided by 2 in the overlapping region. The dimension names, data name, attributes, and original coordinate direction are retained. The coordinate values and the size of dim depend on mode and part: "valid" keeps only the overlap, "full" keeps the union, and "below" or "above" returns only the selected side of center.

Return type:

DataArray

Examples

>>> import xarray as xr
>>> import numpy as np
>>> import erlab.analysis as era
>>> # Create a sample DataArray with uniform coordinates.
>>> da = xr.DataArray(
...     np.array([1, 2, 3, 4, 5, 6]), dims="x", coords={"x": np.linspace(-2, 2, 6)}
... )
>>> sym_da = era.transform.symmetrize(da, dim="x", center=0.0)
>>> print(sym_da)
<xarray.DataArray (x: 6)> Size: 48B
array([2., 4., 6., 6., 4., 2.])
Coordinates:
  * x        (x) float64 48B -2.0 -1.2 -0.4 0.4 1.2 2.0

erlab.analysis.transform.symmetrize_nfold(darr, fold, axes=(0, 1), center=(0.0, 0.0), *, reshape=True, order=1, mode='constant', cval=nan, prefilter=True)[source]¶

Symmetrize a plane by averaging equally spaced rotations.

The input is rotated in the plane defined by axes at angles \(360° i / n\), where \(i = 0, \ldots, n - 1\), and the rotated copies are averaged on a common output grid.

Parameters:

darr (DataArray) – The array to symmetrize. The coordinates along both rotation axes must be evenly spaced and contain at least two points.
fold (int) – The order of the rotational symmetry. Must be at least 2. For example, fold=4 applies 4-fold symmetrization by averaging over the original array and arrays rotated by 90°, 180°, and 270°.
axes (tuple of 2 ints or 2 strings, optional) – The two axes that define the plane of rotation. Default is the first two axes. If strings are provided, they must be valid dimension names in the input array.
center (tuple of 2 floats or dict, optional) – The center of rotation in data coordinates. If a tuple, it is given as values along the dimensions specified in axes. If a dict, it must have keys that correspond exactly to axes. Default is (0, 0).
reshape (bool, default: True) – If True, the output shape is expanded to contain the full extent of all rotated copies. The extent depends on the input coordinates, not on finite data values. If False, the symmetrized result is returned on the original grid. Default is True.
order (int, default: 1) – The order of the spline interpolation, default is 1. The order has to be in the range 0-5.
mode (str, default: 'constant') – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.
cval (float, default: nan) – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.
prefilter (bool, default: True) – Passed to scipy.ndimage.affine_transform(). See the scipy documentation for more information.

Returns:

symmetrized (xarray.DataArray) – A new rotationally averaged array with the same dimension names and order as darr. If reshape is True, the two rotation-axis coordinates and sizes are replaced by the union of the rotated extents at the original coordinate spacing. If False, the original grid is retained. Non-dimension coordinates that depend on either rotation axis are dropped. Other coordinates, the data name, attributes, and Dask-backed execution are preserved. Integer input is converted to a floating dtype so that rotations can be averaged.

Return type:

DataArray