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).

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)

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).

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).

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)

clouddrift.signal

Contents

clouddrift.signal#

Parameters#

Returns#

Examples#

Raises#

References#

See Also#

Parameters#

Returns#

Examples#

Raises#

References#

See Also#

Parameters#

Returns#

Examples#

Raises#

References#

See Also#

Parameters#

Returns#

Examples#

Raises#

References#

See Also#

Parameters#

Returns#

Examples#

Raises#

References#

See Also#