clouddrift.signal.analytic_signal

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

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