Module sswt

ferro_wave::transform

Module sswt 

Expand description

Synchrosqueezed Wavelet Transform (SST / SSWT).

SST (Daubechies, Lu & Wu, Applied and Computational Harmonic Analysis, 2011) reassigns the energy of a Continuous Wavelet Transform from the scale axis onto an instantaneous-frequency axis derived from the local CWT phase. The result is a time-frequency representation that sharpens ridges much like reassignment, but — uniquely among reassignment-type transforms — admits a clean ridge-based reconstruction because of the a^{-3/2} Jacobian weight (Daubechies-Lu-Wu, §3). On signals composed of well-separated mode-type components SST has been proved to converge to the true instantaneous frequency as the wavelet bandwidth shrinks, which makes it the wavelet-side analog of EMD with rigorous theory backing it.

The pipeline is

  1. Compute the CWT W(a, b) via crate::transform::cwt_fft.
  2. Form the one-step forward phase-difference C(a, b) = W(a, b+1) · conj(W(a, b)) (backward fallback at b = n−1).
  3. For each (a, b) with |W(a, b)| > γ, take the instantaneous frequency ω̂(a, b) = −arg(C(a, b)) · fs / (2π) in Hz (the leading minus accounts for ferro-wave’s Σ x[t]·ψ(t−b) CWT convention). This covers (−fs/2, fs/2) without aliasing. Cells below γ are masked as f64::NAN and excluded from the reassignment sum.
  4. Sum T(ω_ℓ, b) = Σ_{a : ω̂(a,b) ∈ bin ℓ} W(a, b) · a^{-3/2} · Δa over the frequency grid {ω_ℓ}.

Two free functions accompany the transform:

  • sswt_extract_ridge tracks the dominant frequency ridge in time using a greedy max-energy walk inside a per-step ±band_width window. The walk seeds at the global SST argmax and walks both directions from there (robust to CWT edge artifacts). This is not the Carmona-Hwang-Torrésani optimal ridge — that is scoped as a follow-up. The greedy variant is sufficient for single-component signals and for the acceptance tests in issue #35.
  • sswt_extract_component inverts SST along a ridge by summing T(ω_ℓ, b) across ±band_width neighboring frequency bins and dividing by the wavelet’s SST inversion constant R_ψ = ∫₀^∞ Ψ̂*(ω) dω / ω (see super::cwt::ContinuousWavelet::sst_inversion_constant). This yields an EMD-like single component reconstructed from one ridge.

§Why one-step discrete phase-difference

Three candidate IF estimators on W(a, b) and the trade-offs that pin our choice:

  • Centered finite-diff of W, then Im((∂_b W)/W) / (2π) — has a multiplicative sinc(f/fs) bias that becomes visible well below Nyquist (~6% at f/fs = 1/10).
  • Centered two-step phase product arg(W[b+1]·conj(W[b−1])) / (2·Δt) — bias-free but arg aliases at |f| > fs/4 (the two-step baseline limits the unambiguous range to half-Nyquist).
  • One-step forward phase product arg(W[b+1]·conj(W[b])) / Δt — bias-free and unambiguous up to full Nyquist (only the one-sample baseline keeps the principal-value range from wrapping). This is the form used here.

Differencing arg W along b and unwrapping is a fourth option, but atan2 unwrap fails precisely where SST cares most — near |W| ≈ γ, where phase jumps by random multiples of 2π. All three phase-product forms above sidestep unwrap entirely.

§Gamma default

SSWTConfig::gamma is Option<f64>. When None, sswt resolves it to 1e-6 · ‖x‖₂, where ‖x‖₂ = sqrt(Σ x[i]²) is computed once over signal.data() before the CWT. The resolved value is exposed on SSWTResult::gamma_used for diagnostics and regression pinning. The amplitude-scaled form is sample-rate / amplitude invariant; the bare literal 1e-6 would fail catastrophically on signals with very small or very large amplitudes.

§Out of scope (deferred follow-ups)

  • Carmona-Hwang-Torrésani optimal-ridge extractor.
  • Multi-component simultaneous ridge tracking.
  • Full inverse SST (isswt) integrating over all bins.
  • Second-order SST (Oberlin 2015) and time-rescaling variants.
  • Serde deserialize of SSWTConfig — the boxed dyn wavelet prevents derive-based Deserialize; serde derives are omitted on the config and present only on the result types.

§References

  • Daubechies, I., Lu, J., & Wu, H.-T. (2011). Synchrosqueezed wavelet transforms: An empirical mode decomposition-like tool. Applied and Computational Harmonic Analysis, 30(2), 243–261. https://doi.org/10.1016/j.acha.2010.08.002 — the canonical paper.
  • Thakur, G., Brevdo, E., Fučkar, N. S., & Wu, H.-T. (2013). The synchrosqueezing algorithm for time-varying spectral analysis: robustness properties and new paleoclimate applications. Signal Processing, 93(5), 1079–1094. https://doi.org/10.1016/j.sigpro.2012.11.029 — robustness analysis.
  • Auger, F., Flandrin, P., Lin, Y.-T., McLaughlin, S., Meignen, S., Oberlin, T., & Wu, H.-T. (2013). Time-frequency reassignment and synchrosqueezing: An overview. IEEE Signal Processing Magazine, 30(6), 32–41. https://doi.org/10.1109/MSP.2013.2265316.

Structs§

GreedyRidgeConfig
Configuration for sswt_extract_ridge.
SSWTConfig
Configuration for sswt.
SSWTPlan
Reusable SSWT execution plan.
SSWTPlanOptions
Options for building an SSWTPlan.
SSWTResult
Result of sswt.

Enums§

SSWTPlanMemoryMode
Planned SSWT memory/performance policy.

Functions§

sswt
Forward Synchrosqueezed Wavelet Transform.
sswt_extract_component
Reconstruct an EMD-like time-domain component from a ridge.
sswt_extract_ridge
Greedy max-energy ridge extractor over time.
sswt_into
Forward SST writing into a caller-supplied result. Reuses every Vec in out (coefficients, frequencies, instantaneous_frequency, time), so rolling-window callers can amortize their cost across windows. Scalar metadata fields are overwritten unconditionally.