Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/overlordgolddragon/ssq
public repo to enable testing -- nothing here!
https://github.com/overlordgolddragon/ssq
Last synced: about 1 month ago
JSON representation
public repo to enable testing -- nothing here!
- Host: GitHub
- URL: https://github.com/overlordgolddragon/ssq
- Owner: OverLordGoldDragon
- Created: 2021-03-26T02:08:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-15T17:14:43.000Z (over 1 year ago)
- Last Synced: 2024-10-14T00:53:28.884Z (2 months ago)
- Language: Python
- Homepage:
- Size: 61.5 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Synchrosqueezing in Python
[](https://travis-ci.com/OverLordGoldDragon/ssqueezepy)
[](https://coveralls.io/github/OverLordGoldDragon/ssqueezepy)
[](https://badge.fury.io/py/ssqueezepy)
[](https://www.codacy.com/gh/OverLordGoldDragon/ssqueezepy/dashboard?utm_source=github.com&utm_medium=referral&utm_content=OverLordGoldDragon/ssqueezepy&utm_campaign=Badge_Grade)
[](https://opensource.org/licenses/MIT)
Synchrosqueezing is a powerful _reassignment method_ that focuses time-frequency representations, and allows extraction of instantaneous amplitudes and frequencies. [Friendly overview.](https://dsp.stackexchange.com/a/71399/50076)
## 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 Python1, 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](https://docs.cupy.dev/en/stable/install.html)
and [PyTorch >= 1.8.0](https://pytorch.org/get-started/locally/) installed (enable via `os.environ['SSQ_GPU'] = '1'`). `pyfftw` optionally supported for maximum CPU FFT speed.
See [Performance guide](https://github.com/OverLordGoldDragon/ssqueezepy/blob/master/ssqueezepy/README.md#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](https://github.com/OverLordGoldDragon/ssqueezepy/tree/master/examples/ridge_extraction)
### 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](https://overlordgolddragon.github.io/test-signals/)
## Introspection
`ssqueezepy` is equipped with a visualization toolkit, useful for exploring wavelet behavior across scales and configurations. (Also see [explanations and code](https://dsp.stackexchange.com/a/72044/50076))
## Minimal example
```python
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](https://github.com/OverLordGoldDragon/ssqueezepy/tree/master/examples/ridge_extraction).
## Learning resources
1. [Continuous Wavelet Transform, & vs STFT](https://ccrma.stanford.edu/~unjung/mylec/WTpart1.html)
2. [Synchrosqueezing's phase transform, intuitively](https://dsp.stackexchange.com/a/72238/50076)
3. [Wavelet time & frequency resolution visuals](https://dsp.stackexchange.com/a/72044/50076)
4. [Why oscillations in SSQ of mixed sines? Separability visuals](https://dsp.stackexchange.com/a/72239/50076)
5. [Zero-padding's effect on spectrum](https://dsp.stackexchange.com/a/70498/50076)
**DSP fundamentals**: I recommend starting with 3b1b's [Fourier Transform](https://youtu.be/spUNpyF58BY), then proceeding with [DSP Guide](https://www.dspguide.com/CH7.PDF) chapters 7-11.
The Discrete Fourier Transform lays the foundation of signal processing with real data. Deeper on DFT coefficients [here](https://dsp.stackexchange.com/a/70395/50076), also [3b1b](https://youtu.be/g8RkArhtCc4).
## Contributors (noteworthy)
- [David Bondesson](https://github.com/DavidBondesson): ridge extraction (`ridge_extraction.py`; `examples/`: `extracting_ridges.py`, `ridge_extraction/README.md`)
## References
`ssqueezepy` was originally ported from MATLAB's [Synchrosqueezing Toolbox](https://github.com/ebrevdo/synchrosqueezing), 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"](https://arxiv.org/abs/1105.0010), Signal Processing 93:1079-1094, 2013.
2. I. Daubechies, S. Maes. ["A Nonlinear squeezing of the Continuous Wavelet Transform Based on Auditory Nerve Models"](https://services.math.duke.edu/%7Eingrid/publications/DM96.pdf).
3. I. Daubechies, J. Lu, H.T. Wu. ["Synchrosqueezed Wavelet Transforms: a Tool for Empirical Mode Decomposition"](https://arxiv.org/pdf/0912.2437.pdf), 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"](https://arxiv.org/abs/1006.2533), SIAM Journal on Mathematical Analysis, 43(5):2078-2095, 2011.
5. Mallat, S. ["Wavelet Tour of Signal Processing 3rd ed"](https://www.di.ens.fr/~mallat/papiers/WaveletTourChap1-2-3.pdf).
6. D. Iatsenko, P. V. E. McClintock, A. Stefanovska. ["On the extraction of instantaneous frequencies from ridges in time-frequency representations of signals"](https://arxiv.org/pdf/1310.7276.pdf).
## License
ssqueezepy is MIT licensed, as found in the [LICENSE](https://github.com/OverLordGoldDragon/ssqueezepy/blob/master/LICENSE) file. Some source functions may be under other authorship/licenses; see [NOTICE.txt](https://github.com/OverLordGoldDragon/ssqueezepy/blob/master/NOTICE.txt).