clouddrift.wavelet.morse_wavelet_transform

clouddrift.wavelet.morse_wavelet_transform(x: ndarray, gamma: float, beta: float, radian_frequency: ndarray, complex: bool = False, order: int = 1, normalization: str = 'bandpass', boundary: str = 'mirror', time_axis: int = -1) → tuple[ndarray, ndarray] | ndarray

Apply a continuous wavelet transform to an input signal using the generalized Morse wavelets of Olhede and Walden (2002). The wavelet transform is normalized differently for complex-valued input than for real-valued input, and this in turns depends on whether the optional argument normalization is set to "bandpass" or "energy" normalizations.

Parameters

xnp.ndarray

Real- or complex-valued signals. The time axis is assumed to be the last. If not, specify optional argument time_axis.

gammafloat

Gamma parameter of the Morse wavelets.

betafloat

Beta parameter of the Morse wavelets.

radian_frequencynp.ndarray

An array of radian frequencies at which the Fourier transform of the wavelets reach their maximum amplitudes. radian_frequency is typically between 0 and 2 * np.pi * 0.5, the normalized Nyquist radian frequency.

complexboolean, optional

Specify explicitely if the input signal x is a complex signal. Default is False which means that the input is real but that is not explicitely tested by the function. This choice affects the normalization of the outputs and their interpretation. See examples below.

time_axisint, optional

Axis on which the time is defined for input x (default is last, or -1).

normalizationstr, optional

Normalization for the wavelet transforms. By default it is assumed to be "bandpass" which uses a bandpass normalization, meaning that the FFT of the wavelets have peak value of 2 for all central frequencies radian_frequency. However, if the optional argument complex=True is specified, the wavelets will be divided by 2 so that the total variance of the input complex signal is equal to the sum of the variances of the returned analytic (positive) and conjugate analytic (negative) parts. See examples below. The other option is "energy" which uses the unit energy normalization. In this last case, the time-domain wavelet energies np.sum(np.abs(wave)**2) are always unity.

boundarystr, optional

The boundary condition to be imposed at the edges of the input signal x. Allowed values are "mirror", "zeros", and "periodic". Default is "mirror".

orderint, optional

Order of Morse wavelets, default is 1.

Returns

If the input signal is real as specificied by complex=False:

wtxnp.ndarray

Time-domain wavelet transform of input x with shape ((x shape without time_axis), orders, frequencies, time_axis) but with dimensions of length 1 removed (squeezed).

If the input signal is complex as specificied by complex=True, a tuple is returned:

wtx_pnp.array

Time-domain positive wavelet transform of input x with shape ((x shape without time_axis), frequencies, orders), but with dimensions of length 1 removed (squeezed).

wtx_nnp.array

Time-domain negative wavelet transform of input x with shape ((x shape without time_axis), frequencies, orders), but with dimensions of length 1 removed (squeezed).

Examples

Apply a wavelet transform with a Morse wavelet with gamma parameter 3, beta parameter 4, at radian frequency 0.2 cycles per unit time:

>>> x = np.random.random(1024)
>>> wtx = morse_wavelet_transform(x, 3, 4, np.array([2*np.pi*0.2]))

Apply a wavelet transform with a Morse wavelet with gamma parameter 3, beta parameter 4, for a complex input signal at radian frequency 0.2 cycles per unit time. This case returns the analytic and conjugate analytic components:

>>> z = np.random.random(1024) + 1j*np.random.random(1024)
>>> wtz_p, wtz_n = morse_wavelet_transform(z, 3, 4, np.array([2*np.pi*0.2]), complex=True)

The same result as above can be otained by applying the Morse transform on the real and imaginary component of z and recombining the results as follows for the “bandpass” normalization: >>> wtz_real = morse_wavelet_transform(np.real(z)), 3, 4, np.array([2*np.pi*0.2])) >>> wtz_imag = morse_wavelet_transform(np.imag(z)), 3, 4, np.array([2*np.pi*0.2])) >>> wtz_p, wtz_n = (wtz_real + 1j*wtz_imag) / 2, (wtz_real - 1j*wtz_imag) / 2

For the “energy” normalization, the analytic and conjugate analytic components are obtained as follows with this alternative method: >>> wtz_real = morse_wavelet_transform(np.real(z)), 3, 4, np.array([2*np.pi*0.2])) >>> wtz_imag = morse_wavelet_transform(np.imag(z)), 3, 4, np.array([2*np.pi*0.2])) >>> wtz_p, wtz_n = (wtz_real + 1j*wtz_imag) / np.sqrt(2), (wtz_real - 1j*wtz_imag) / np.sqrt(2)

The input signal can have an arbitrary number of dimensions but its time_axis must be specified if it is not the last:

>>> x = np.random.random((1024,10,15))
>>> wtx = morse_wavelet_transform(x, 3, 4, np.array([2*np.pi*0.2]), time_axis=0)

The default way to handle the boundary conditions is to mirror the ends points but this can be changed by specifying the chosen boundary method:

>>> x = np.random.random((10,15,1024))
>>> wtx = morse_wavelet_transform(x, 3, 4, np.array([2*np.pi*0.2]), boundary="periodic")

This function can be used to conduct a time-frequency analysis of the input signal by specifying a range of randian frequencies using the morse_logspace_freq function as an example:

>>> x = np.random.random(1024)
>>> gamma = 3
>>> beta = 4
>>> radian_frequency = morse_logspace_freq(gamma, beta, np.shape(x)[0])
>>> wtx = morse_wavelet_transform(x, gamma, beta, radian_frequency)

Raises

ValueError

If the time axis is outside of the valid range ([-1, np.ndim(x)-1]). If boundary optional argument is not in [“mirror”, “zeros”, “periodic”]``. If normalization optional argument is not in [“bandpass”, “energy”]``.

See Also

morse_wavelet(), wavelet_transform(), morse_logspace_freq()