clouddrift.wavelet.morse_logspace_freq

clouddrift.wavelet.morse_logspace_freq(gamma: float, beta: float, length: int, highset: tuple[float] | None = (0.1, 3.141592653589793), lowset: tuple[float] | None = (5, 0), density: int | None = 4) → ndarray

Compute logarithmically-spaced frequencies for generalized Morse wavelets with parameters gamma and beta. This is a useful function to obtain the frequencies needed for time-frequency analyses using wavelets. If radian_frequencies is the output, np.log(radian_frequencies) is uniformly spaced, following convention for wavelet analysis. See Lilly (2017), doi: 10.1098/rspa.2016.0776.

Default settings to compute the frequencies can be changed by passing optional arguments lowset, highset, and density. See below.

Parameters

gammafloat

Gamma parameter of the Morse wavelets.

betafloat

Beta parameter of the Morse wavelets.

lengthint

Length of the Morse wavelets and input signals.

highsettuple of floats, optional.

Tuple of values (eta, high) used for high-frequency cutoff calculation. The highest frequency is set to be the minimum of a specified value and a cutoff frequency based on a Nyquist overlap condition: the highest frequency is the minimum of the specified value high, and the largest frequency for which the wavelet will satisfy the threshold level eta. Here eta be a number between zero and one specifying the ratio of a frequency-domain wavelet at the Nyquist frequency to its peak value. Default is (eta, high) = (0.1, np.pi).

lowsettuple of floats, optional.

Tupe of values (P, low) set used for low-frequency cutoff calculation based on an endpoint overlap condition. The lowest frequency is set such that the lowest-frequency wavelet will reach some number P, called the packing number, times its central window width at the ends of the time series. A choice of P=1 corresponds to roughly 95% of the time-domain wavelet energy being contained within the time series endpoints for a wavelet at the center of the domain. The second value of the tuple is the absolute lowest frequency. Default is (P, low) = (5, 0).

densityint, optional

This optional argument controls the number of points in the returned frequency array. Higher values of density mean more overlap in the frequency domain between transforms. When density=1, the peak of one wavelet is located at the half-power points of the adjacent wavelet. The default density=4 means that four other wavelets will occur between the peak of one wavelet and its half-power point.

Returns

radian_frequencynp.ndarray

Logarithmically-spaced frequencies in radians cycles per unit time, sorted in descending order.

Examples

Generate a frequency array for the generalized Morse wavelet with parameters gamma=3 and beta=5 for a time series of length n=1024:

>>> radian_frequency = morse_logspace_freq(3, 5, 1024)
>>> radian_frequency = morse_logspace_freq(3, 5, 1024, highset=(0.2, np.pi), lowset=(5, 0))
>>> radian_frequency = morse_logspace_freq(3, 5, 1024, highset=(0.2, np.pi), lowset=(5, 0), density=10)

See Also

morse_wavelet(), morse_freq(), morse_properties()