clouddrift.signal#

This module provides signal processing functions.

Functions

analytic_signal(x[, boundary, time_axis])

Return the analytic signal from a real-valued signal or the analytic and conjugate analytic signals from a complex-valued signal.

cartesian_to_rotary(ua, va[, time_axis])

Return rotary signals (wp,wn) from analytic Cartesian signals (ua,va).

ellipse_parameters(xa, ya)

Return the instantaneous parameters of a modulated elliptical signal from its analytic Cartesian signals.

modulated_ellipse_signal(kappa, lambda_, ...)

Return the analytic Cartesian signals (xa, ya) from the instantaneous parameters of a modulated elliptical signal.

rotary_to_cartesian(wp, wn[, time_axis])

Return Cartesian analytic signals (ua, va) from rotary signals (wp, wn) as ua = wp + wn and va = -1j * (wp - wn).

clouddrift.signal.analytic_signal(x: ndarray | DataArray, boundary: str | None = 'mirror', time_axis: int | None = -1) ndarray | Tuple[ndarray, ndarray][source]#

Return the analytic signal from a real-valued signal or the analytic and conjugate analytic signals from a complex-valued signal.

If the input is a real-valued signal, the analytic signal is calculated as the inverse Fourier transform of the positive-frequency part of the Fourier transform. If the input is a complex-valued signal, the conjugate analytic signal is additionally calculated as the inverse Fourier transform of the positive-frequency part of the Fourier transform of the complex conjugate of the input signal.

For a complex-valued signal, the mean is evenly divided between the analytic and conjugate analytic signal.

The calculation is performed along the last axis of the input array by default. Alternatively, the user can specify the time axis of the input. The user can also specify the boundary conditions to be applied to the input array (default is “mirror”).

Parameters#

xarray_like

Real- or complex-valued signal.

boundarystr, optional

The boundary condition to be imposed at the edges of the time series. Allowed values are “mirror”, “zeros”, and “periodic”. Default is “mirror”.

time_axisint, optional

Axis on which the time is defined (default is -1).

Returns#

xanp.ndarray

Analytic signal. It is a tuple if the input is a complex-valed signal with the first element being the analytic signal and the second element being the conjugate analytic signal.

Examples#

To obtain the analytic signal of a real-valued signal:

>>> x = np.random.rand(99)
>>> xa = analytic_signal(x)

To obtain the analytic and conjugate analytic signals of a complex-valued signal:

>>> w = np.random.rand(99)+1j*np.random.rand(99)
>>> wp, wn = analytic_signal(w)

To specify that a periodic boundary condition should be used:

>>> x = np.random.rand(99)
>>> xa = analytic_signal(x, boundary="periodic")

To specify that the time axis is along the first axis and apply zero boundary conditions:

>>> x = np.random.rand(100, 99)
>>> xa = analytic_signal(x, time_axis=0, boundary="zeros")

Raises#

ValueError

If the time axis is outside of the valid range ([-1, N-1]). If boundary not in ["mirror", "zeros", "periodic"].

References#

[1] Gabor D. 1946 Theory of communication. Proc. IEE 93, 429–457. (10.1049/ji-1.1947.0015).

[2] Lilly JM, Olhede SC. 2010 Bivariate instantaneous frequency and bandwidth. IEEE T. Signal Proces. 58, 591–603. (10.1109/TSP.2009.2031729).

See Also#

rotary_to_cartesian(), cartesian_to_rotary()

clouddrift.signal.cartesian_to_rotary(ua: ndarray | DataArray, va: ndarray | DataArray, time_axis: int | None = -1) Tuple[ndarray, ndarray][source]#

Return rotary signals (wp,wn) from analytic Cartesian signals (ua,va).

If ua is the analytic signal from real-valued signal u, and va the analytic signal from real-valued signal v, then the positive (counterclockwise) and negative (clockwise) signals are defined by wp = 0.5*(up+1j*vp), wp = 0.5*(up-1j*vp).

This function is the inverse of rotary_to_cartesian().

Parameters#

uaarray_like

Complex-valued analytic signal for first Cartesian component (zonal, east-west)

vaarray_like

Complex-valued analytic signal for second Cartesian component (meridional, north-south)

time_axisint, optional

The axis of the time array. Default is -1, which corresponds to the last axis.

Returns#

wpnp.ndarray

Complex-valued positive (counterclockwise) rotary signal.

wnnp.ndarray

Complex-valued negative (clockwise) rotary signal.

Examples#

To obtain the rotary signals from a pair of real-valued signal:

>>> u = np.random.rand(99)
>>> v = np.random.rand(99)
>>> wp, wn = cartesian_to_rotary(analytic_signal(u), analytic_signal(v))

To specify that the time axis is along the first axis:

>>> u = np.random.rand(100, 99)
>>> v = np.random.rand(100, 99)
>>> wp, wn = cartesian_to_rotary(analytic_signal(u), analytic_signal(v), time_axis=0)

Raises#

ValueError

If the input arrays do not have the same shape. If the time axis is outside of the valid range ([-1, N-1]).

References#

Lilly JM, Olhede SC. 2010 Bivariate instantaneous frequency and bandwidth. IEEE T. Signal Proces. 58, 591–603. (10.1109/TSP.2009.2031729)

See Also#

analytic_signal(), rotary_to_cartesian()

clouddrift.signal.ellipse_parameters(xa: ndarray | DataArray, ya: ndarray | DataArray) Tuple[ndarray, ndarray, ndarray, ndarray][source]#

Return the instantaneous parameters of a modulated elliptical signal from its analytic Cartesian signals.

Parameters#

xaarray_like

Complex-valued analytic signal for first Cartesian component (zonal, east-west).

yaarray_like

Complex-valued analytic signal for second Cartesian component (meridional, north-south).

Returns#

kappanp.ndarray

Ellipse root-mean-square amplitude.

lambdanp.ndarray

Ellipse linearity between -1 and 1, or departure from circular motion (lambda=0).

thetanp.ndarray

Ellipse orientation in radian.

phinp.ndarray

Ellipse phase in radian.

Examples#

To obtain the ellipse parameters from a pair of real-valued signals (x, y):

>>> kappa, lambda, theta, phi = ellipse_parameters(analytic_signal(x), analytic_signal(y))

Raises#

ValueError

If the input arrays do not have the same shape.

References#

Lilly JM, Olhede SC. 2010 Bivariate instantaneous frequency and bandwidth. IEEE T. Signal Proces. 58, 591–603. (10.1109/TSP.2009.2031729).

See Also#

modulated_ellipse_signal(), analytic_signal(), rotary_to_cartesian(), cartesian_to_rotary()

clouddrift.signal.modulated_ellipse_signal(kappa: ndarray | DataArray, lambda_: ndarray | DataArray, theta: ndarray | DataArray, phi: ndarray | DataArray) Tuple[ndarray, ndarray][source]#

Return the analytic Cartesian signals (xa, ya) from the instantaneous parameters of a modulated elliptical signal.

This function is the inverse of ellipse_parameters().

Parameters#

kappaarray_like

Ellipse root-mean-square amplitude.

lambdaarray_like

Ellipse linearity between -1 and 1, or departure from circular motion (lambda=0).

thetaarray_like

Ellipse orientation in radian.

phiarray_like

Ellipse phase in radian.

time_axisint, optional

The axis of the time array. Default is -1, which corresponds to the last axis.

Returns#

xanp.ndarray

Complex-valued analytic signal for first Cartesian component (zonal, east-west).

yanp.ndarray

Complex-valued analytic signal for second Cartesian component (meridional, north-south).

Examples#

To obtain the analytic signals from the instantaneous parameters of a modulated elliptical signal:

>>> xa, ya = modulated_ellipse_signal(kappa, lambda, theta, phi)

Raises#

ValueError

If the input arrays do not have the same shape.

References#

Lilly JM, Olhede SC. 2010 Bivariate instantaneous frequency and bandwidth. IEEE T. Signal Proces. 58, 591–603. (10.1109/TSP.2009.2031729).

See Also#

ellipse_parameters(), analytic_signal(), rotary_to_cartesian(), cartesian_to_rotary()

clouddrift.signal.rotary_to_cartesian(wp: ndarray | DataArray, wn: ndarray | DataArray, time_axis: int | None = -1) Tuple[ndarray, ndarray][source]#

Return Cartesian analytic signals (ua, va) from rotary signals (wp, wn) as ua = wp + wn and va = -1j * (wp - wn).

This function is the inverse of cartesian_to_rotary().

Parameters#

wparray_like

Complex-valued positive (counterclockwise) rotary signal.

wnarray_like

Complex-valued negative (clockwise) rotary signal.

time_axisint, optional

The axis of the time array. Default is -1, which corresponds to the last axis.

Returns#

uaarray_like

Complex-valued analytic signal, first Cartesian component (zonal, east-west)

vaarray_like

Complex-valued analytic signal, second Cartesian component (meridional, north-south)

Examples#

To obtain the Cartesian analytic signals from a pair of rotary signals (wp,wn):

>>> ua, va = rotary_to_cartesian(wp, wn)

To specify that the time axis is along the first axis:

>>> ua, va = rotary_to_cartesian(wp, wn, time_axis=0)

Raises#

ValueError

If the input arrays do not have the same shape. If the time axis is outside of the valid range ([-1, N-1]).

References#

Lilly JM, Olhede SC. 2010 Bivariate instantaneous frequency and bandwidth. IEEE T. Signal Proces. 58, 591–603. (10.1109/TSP.2009.2031729)

See Also#

analytic_signal(), cartesian_to_rotary()