pymodalib.algorithms.wavelet module

Wavelet transform.

wavelet_transform(signal: numpy.ndarray, fs: float, fmin: float = None, fmax: float = None, resolution: float = 1, cut_edges: bool = False, wavelet: str = 'Lognorm', preprocess: bool = True, rel_tolerance: float = 0.01, implementation='python', padding: str = 'predictive', return_opt: bool = False, parallel: bool = None, *args, **kwargs) → Tuple[numpy.ndarray, numpy.ndarray]

Wavelet transform function.

Note

If return_opt == True, a dictionary will be returned in addition to the normal return values. This dictionary contains parameters used by the function.

Parameters:
  • signal (ndarray) – [1D array] The signal to perform the wavelet transform on.
  • fs (float) – The sampling frequency of the signal.
  • fmin (float) – The minimal frequency for which to calculate the WT. If left to the default value, the function will use the minimal frequency for which at least one WT coefficient is determined up to a specified relative accuracy (rel_tolerance) with respect to boundary errors.
  • fmax (float) – (Default = fs/2) The maximal frequency for which to calculate the WT.
  • resolution (float) – (Default = 1) The wavelet resolution parameter, which determines the trade-off between the time and frequency resolutions; the higher it is, the closer in frequency components can be resolved in WT, but the closer the slower time-variations, e.g. amplitude/frequency modulation, can be reliably represented. For the way it is introduced for each wavelet, see Appendix E in [1], while if the wavelet is user-defined in terms of its function in frequency and/or time (see wavelet parameter), then resolution has no effect.
  • cut_edges (bool) – (Default = False) Whether WT coefficients should be set to NaN out of the influence (see [1]). Use cut_edges=True if you wish to analyze the WT only within the cone of influence, which is recommended if you are estimating only the time-averaged quantities.
  • wavelet ({“Lognorm”, “Morlet”, “Morse-a”}) – (Default = “Lognorm”) Wavelet used in the WT calculation. For a list of all supported names and their properties, see Appendix E in [1]. Note: supplying a wavelet using a custom function is not supported in PyMODAlib.
  • preprocess (bool) – (Default = True) Whether to perform signal preprocessing, which consists of subtracting third-order polynomial fit and then bandpassing the signal in the band of interest (fmin-fmax).
  • padding ({“predictive”, 0, “symmetric”, “none”, “periodic”}, float) – (Default = “predictive”) Padding to use when calculating the transform. For all paddings and their effects, see [1]. Most useful are the zero-padding, for which boundary errors are well-determined, and “predictive” padding, for which they are most reduced, while other choices have limited usefulness. Note: if a List containing two padding parameters from the accepted values is passed, the first value will be used for left-padding and the second value for right-padding.
  • rel_tolerance (float) – (Default = 0.01) Commonly referred to as epsilon in [1], this parameter is the relative tolerance as a percentage, which specifies the cone of influence for the WT (i.e. the range of WT coefficients which are determined up to this accuracy in respect of boundary errors). Also determintes the minimal number of values to pad the signal with,so that the relative constribution of effects of implicit periodic signal continutation due to convolution in the frequency domain is smaller. See [1] for details.
  • implementation ({“matlab”, “python”}, optional) – (Default value = “python”) Whether to use the MATLAB implementation, or the Python implementation. The MATLAB implementation requires the MATLAB Runtime.
  • return_opt (bool) – (Default value = False) Whether to return a dictionary containing the parameters used with the wavelet transform. This can be useful if fmin was left to its default value, since it will contain the value of fmin which was used.
  • parallel (bool, None) – Whether to parallelize the algorithm. This may improve performance by up to 25% for larger signals, but it also increases memory usage.
  • *args (Any, optional) – Any other arguments to pass to the wavelet transform implementation.
  • **kwargs (Any, optional) – Any other keyword arguments to pass to the wavelet transform implementation.
Returns:

  • wt (ndarray) – [2D array, complex] The wavelet transform, whose rows correspond to frequencies and columns to time. Take the absolute value to get the amplitude. Dimensions: (FNxL) where FN is the number of frequencies and L is the length of the signal in samples.
  • freq (ndarray) – [1D array] The frequencies corresponding to the rows of wt.

Notes

Author: Dmytro Iatsenko.

[1]D. Iatsenko, A. Stefanovska and P.V.E. McClintock, “Linear and synchrosqueezed time-frequency representations revisited. Part I: Overview, standards of use, related issues and algorithms.” {preprint:arXiv:1310.7215}
[2]D. Iatsenko, A. Stefanovska and P.V.E. McClintock, “Linear and synchrosqueezed time-frequency representations revisited. Part II: Resolution, reconstruction and concentration.” {preprint:arXiv:1310.7274}