OverLordGoldDragon / ssq

public repo to enable testing -- nothing here!

Synchrosqueezing in Python

Synchrosqueezing is a powerful reassignment method that focuses time-frequency representations, and allows extraction of instantaneous amplitudes and frequencies. Friendly overview.

Features

• Continuous Wavelet Transform (CWT), forward & inverse, and its Synchrosqueezing
• Short-Time Fourier Transform (STFT), forward & inverse, and its Synchrosqueezing
• Wavelet visualizations and testing suite
• Generalized Morse Wavelets
• Ridge extraction
• Speed: fastest wavelet transforms in Python¹, beating MATLAB

_{1: feel free to open Issue showing otherwise}

Installation

pip install ssqueezepy. Or, for latest version (most likely stable):

pip install git+https://github.com/OverLordGoldDragon/ssqueezepy

GPU & CPU acceleration

Multi-threaded execution is enabled by default (disable via os.environ['SSQ_PARALLEL'] = '0'). GPU requires CuPy >= 8.0.0 and PyTorch >= 1.8.0 installed (enable via os.environ['SSQ_GPU'] = '1'). pyfftw optionally supported for maximum CPU FFT speed. See Performance guide.

Examples

1. Signal recovery under severe noise

2. Medical: EEG

3. Testing suite: CWT vs STFT, reflect-added parallel linear chirp

4. Ridge extraction: cubic polynom. F.M. + pure tone; noiseless & 1.69dB SNR

More

5. Testing suite: GMW vs Morlet, reflect-added hyperbolic chirp (extreme time-loc.)

6. Higher-order GMW CWT, reflect-added parallel linear chirp, 3.06dB SNR

More examples

Introspection

ssqueezepy is equipped with a visualization toolkit, useful for exploring wavelet behavior across scales and configurations. (Also see explanations and code)

---

Minimal example

import numpy as np
import matplotlib.pyplot as plt
from ssqueezepy import ssq_cwt, ssq_stft

def viz(x, Tx, Wx):
    plt.imshow(np.abs(Wx), aspect='auto', cmap='jet')
    plt.show()
    plt.imshow(np.flipud(np.abs(Tx)), aspect='auto', vmin=0, vmax=.2, cmap='jet')
    plt.show()   

#%%# Define signal ####################################    
N = 2048
t = np.linspace(0, 10, N, endpoint=False)
xo = np.cos(2 * np.pi * 2 * (np.exp(t / 2.2) - 1))
xo += xo[::-1]  # add self reflected
x = xo + np.sqrt(2) * np.random.randn(N)  # add noise

plt.plot(xo); plt.show()
plt.plot(x);  plt.show()

#%%# CWT + SSQ CWT ####################################
Twxo, Wxo, *_ = ssq_cwt(xo)
viz(xo, Twxo, Wxo)

Twx, Wx, *_ = ssq_cwt(x)
viz(x, Twx, Wx)

#%%# STFT + SSQ STFT ##################################
Tsxo, Sxo, *_ = ssq_stft(xo)
viz(xo, Tsxo, np.flipud(Sxo))

Tsx, Sx, *_ = ssq_stft(x)
viz(x, Tsx, np.flipud(Sx))

Also see ridge extraction README.

Learning resources

1. Continuous Wavelet Transform, & vs STFT
2. Synchrosqueezing's phase transform, intuitively
3. Wavelet time & frequency resolution visuals
4. Why oscillations in SSQ of mixed sines? Separability visuals
5. Zero-padding's effect on spectrum

DSP fundamentals: I recommend starting with 3b1b's Fourier Transform, then proceeding with DSP Guide chapters 7-11. The Discrete Fourier Transform lays the foundation of signal processing with real data. Deeper on DFT coefficients here, also 3b1b.

Contributors (noteworthy)

• David Bondesson: ridge extraction (ridge_extraction.py; examples/: extracting_ridges.py, ridge_extraction/README.md)

References

ssqueezepy was originally ported from MATLAB's Synchrosqueezing Toolbox, authored by E. Brevdo and G. Thakur [1]. Synchrosqueezed Wavelet Transform was introduced by I. Daubechies and S. Maes [2], which was followed-up in [3], and adapted to STFT in [4]. Many implementation details draw from [5]. Ridge extraction based on [6].

1. G. Thakur, E. Brevdo, N.-S. Fučkar, and H.-T. Wu. "The Synchrosqueezing algorithm for time-varying spectral analysis: robustness properties and new paleoclimate applications", Signal Processing 93:1079-1094, 2013.
2. I. Daubechies, S. Maes. "A Nonlinear squeezing of the Continuous Wavelet Transform Based on Auditory Nerve Models".
3. I. Daubechies, J. Lu, H.T. Wu. "Synchrosqueezed Wavelet Transforms: a Tool for Empirical Mode Decomposition", Applied and Computational Harmonic Analysis 30(2):243-261, 2011.
4. G. Thakur, H.T. Wu. "Synchrosqueezing-based Recovery of Instantaneous Frequency from Nonuniform Samples", SIAM Journal on Mathematical Analysis, 43(5):2078-2095, 2011.
5. Mallat, S. "Wavelet Tour of Signal Processing 3rd ed".
6. D. Iatsenko, P. V. E. McClintock, A. Stefanovska. "On the extraction of instantaneous frequencies from ridges in time-frequency representations of signals".

License

ssqueezepy is MIT licensed, as found in the LICENSE file. Some source functions may be under other authorship/licenses; see NOTICE.txt.