Skip to main content

Advanced Wavelet Analysis Guide

This guide describes the advanced analysis modules built on top of IronWave’ core transforms:

  • Wavelet coherence (time–frequency cross-signal analysis).
  • Matching Pursuit and Orthogonal Matching Pursuit (sparse decompositions).
  • Multifractal analysis via wavelet leaders.
  • Streaming analytics built on streaming DWT/MODWT/SWT.

It focuses on what each feature is good for, recommended settings, and practical trade-offs.

For formal mathematical validation and references, see MATHEMATICAL_VALIDATION.md.

1. Wavelet Coherence​

Module: analysis::coherence

1.1 What it is​

Wavelet coherence generalizes correlation to the time–frequency plane:

  • Computes the cross-wavelet spectrum W_xy = W_x \overline{W_y} from CWTs of two signals.
  • Applies Gaussian smoothing in time and log-scale to obtain a smoothed cross-spectrum and auto-spectra.
  • Forms coherence as:
    • R²(s, t) = |S(W_xy)|² / (S(|W_x|²) S(|W_y|²)), with values in [0, 1].
  • Extracts phase information to identify lead/lag relationships.

1.2 When to use it​

Good for:

  • Finance
    • Cross-asset correlation dynamics.
    • Lead/lag analysis between instruments or indices.
    • Time–scale-specific co-movement.
  • General signal processing
    • Coherence between sensors, channels, or modalities.
    • Climate and geophysical signal relationships.
    • Neuroscience (e.g., EEG coherence).

Less useful when:

  • You only care about global correlation.
  • The signals are extremely short or dominated by single spikes (simpler tools may suffice).

  • Wavelet

    • Default: ComplexMorlet::new(6.0, 1.0) (standard choice in many CWT applications).
    • Use other complex wavelets (Mexican Hat, Paul) if you have specific bandpass or morphology requirements.

  • Scales

    • Choose scales that cover the time-scales of interest:
      • For N samples and a sampling interval Δt, you might use a logarithmic grid spanning from ~Δt to a fraction of the series length.
    • For many financial applications, a modest number of scales (e.g., 16–64) is a good starting point.

  • FFT vs direct CWT

    • The coherence implementation can call either cwt or cwt_fft.
    • Default behavior:
      • Uses direct CWT for small problems.
      • Switches to FFT-based CWT internally for larger N and scale counts when CoherenceConfig allows it.
    • You typically don’t need to override this unless you know your workload very well.

  • Smoothing

    • Start with the default CoherenceConfig values.
    • If coherence looks too noisy, increase smoothing slightly; if it looks overly blurred, reduce smoothing.

1.4 Interpreting results​

  • Coherence close to 1:
    • Strong local correlation at that time and scale.
  • Coherence close to 0:
    • Weak or no local correlation.
  • Phase:
    • Phase near 0: signals move together (in phase).
    • Positive vs negative phase indicates lead/lag; the exact interpretation depends on sign conventions and context.

The examples under examples/wavelet_coherence.rs are a good starting point.

2. Matching Pursuit and OMP​

Module: decomposition::matching_pursuit

2.1 What it is​

Matching Pursuit (MP) and Orthogonal Matching Pursuit (OMP) provide sparse expansions of a signal as a sum of dictionary atoms:

  • A dictionary is a set of precomputed wavelet atoms at different scales and positions.
  • Matching Pursuit:
    • Iteratively selects the atom with the largest inner product with the residual.
    • Updates the residual by subtracting that atom’s contribution.
  • Orthogonal Matching Pursuit:
    • Same greedy selection, but projects onto the span of all selected atoms using least-squares (Cholesky).
    • Generally yields better, more stable reconstructions.

2.2 When to use it​

Good for:

  • Feature extraction and sparse coding
    • Identify a small number of dominant wavelet patterns.
    • Create low-dimensional representations for further modeling.
  • Signal approximation / compression
    • Approximate a signal with a limited number of atoms.
  • Pattern discovery
    • See which atoms (scales, locations, wavelet families) are most active.

Less useful when:

  • You do not need sparsity or interpretability.
  • You only need standard multi-scale decompositions.

  • Dictionary construction

    • Use a mix of Haar and Db4 (or Sym4) for many financial and general-purpose tasks.
    • Limit max_scale to a small number (e.g., 3–5) when signal length is moderate (hundreds to a few thousand samples).
    • Do not push dictionary size to extremes (e.g., millions of atoms) without careful benchmarking.

  • Number of iterations

    • For quick approximate decompositions: ~10–20 iterations.
    • For higher fidelity: 20–50 iterations or until residual energy stops decreasing significantly.

  • Algorithm choice

    • OMP is preferred when:
      • Reconstruction quality is important.
      • You care about convergence behavior (residual energy decreasing monotonically up to numerical tolerance).
    • MP is acceptable when:
      • You need a fast, rough decomposition.
      • You’re more interested in the first few dominant atoms than in precise reconstruction.

2.4 Practical notes​

  • Monitor residual energy per iteration; use it to adapt stopping criteria.
  • Keep an eye on memory usage if you increase dictionary size or signal length.

Examples:

  • examples/matching_pursuit.rs demonstrates several typical use cases.

3. Multifractal Analysis (Wavelet Leaders)​

Module: analysis::multifractal

3.1 What it is​

Multifractal analysis characterizes scaling and local regularity beyond a single Hurst exponent:

  • Hurst exponent H:
    • Captures long-range dependence and persistence/anti-persistence.
  • Multifractal spectrum f(α):
    • Describes distribution of Hölder exponents α (local regularity).
    • A wide spectrum indicates strongly multifractal behavior; a narrow spectrum suggests monofractality.

IronWave implements a wavelet-leader-based approach:

  • Uses MODWT for variance scaling and wavelet leaders defined on a cone of neighboring coefficients across scales.
  • Computes structure functions S(j, q) and scaling exponents ζ(q).
  • Applies a Legendre transform to obtain an estimated f(α) spectrum for α ≥ 0.

3.2 When to use it​

Good for:

  • Financial time series
    • Volatility persistence and multifractality in returns or volatility.
    • Testing deviations from random walk / efficient market assumptions.
  • Other domains
    • Geophysics, climate, hydrology: scaling in environmental time series.
    • Turbulence and cascade processes.

Less useful when:

  • Your process is clearly short-memory and well-modeled by simple ARMA processes.
  • Data length is too short to support multiple scales (e.g., heavily constrained by sample size).

  • Wavelet

    • Daubechies Db2 or Db4 are standard choices.

  • Moments q

    • Typical range: −2 to +2, step 0.5 or similar.
    • Avoid extreme q values on modest-length data; they can amplify noise and rare events.

  • Scale range

    • Avoid the very finest scale (j=1) unless you know it is reliable; boundary effects and noise dominate there.
    • Use a reasonable range of scales where structure functions behave approximately linearly in log-space.

  • Bootstrap

    • For exploratory work or where speed is critical, you can start with zero bootstrap samples.
    • For confidence intervals, enable bootstrap with a moderate number of samples and, if needed, a fixed RNG seed for reproducibility.

3.4 Diagnostics​

The module exposes diagnostic helpers:

  • Curvature-based multifractality score |ζ''(0)|:
    • Small → near linear ζ(q) (monofractal-like).
    • Larger → more curvature in ζ(q) (more multifractal).
  • Linearity R² for the fit ζ(q) ≈ a q + b:
    • Close to 1 for monofractal-like processes.
    • Less than 1 for processes with nonlinear ζ(q).

Use these alongside the estimated spectrum width and α-range to characterize multifractality.

4. Streaming Analytics​

Modules: streaming::*, plus financial streaming helpers.

4.1 What they provide​

Building on StreamingDWT, StreamingMODWT, and StreamingSWT, IronWave offers:

  • Streaming denoising.
  • Streaming volatility and energy tracking.
  • Streaming jump detection.
  • Streaming regime detection.
  • Event-driven monitoring (thresholds, jumps, regime changes).

These tools maintain bounded memory and incremental updates suitable for tick-by-tick data.

4.2 When to use them​

Good for:

  • High-frequency trading or real-time monitoring.
  • Any application where you must process streams in near real time with predictable latency.

Less appropriate when:

  • You are purely working with offline/historical data.
  • Your analysis requires transforms that are batch-only (CWT, WPT, EMD/EEMD).
  • Window size:
    • Choose based on the horizon of interest (e.g., 100–1000 samples).
  • Update triggers:
    • Use “every tick” for small windows; use sample-count triggers for heavier configurations.
  • Transform choice:
    • StreamingMODWT is the default for most financial analysis (volatility, regime).
    • StreamingDWT or StreamingSWT can be used when you want different trade-offs between redundancy and speed.

For full details and limitations (including why streaming CWT/WPT/EMD are not implemented), see STREAMING_SUPPORT.md.

5. How These Pieces Fit Together​

Typical combinations:

  • Cross-signal, multi-scale relationships

    • Use batch CWT → wavelet coherence.
    • Supplement with multiscale correlations via MODWT.

  • Sparse factor extraction

    • Build a multi-wavelet dictionary (e.g., Haar + Db4).
    • Run OMP for 20–50 iterations, monitor residual energy.

  • Scaling and persistence profiling

    • Use MODWT-based Hurst estimation.
    • Extend to wavelet-leader multifractal spectrum for richer characterization.

  • Real-time risk and monitoring

    • Use streaming MODWT-based analytics (volatility, jumps, regimes).
    • Trigger events into your risk/monitoring pipeline.

For more context on design and future plans, see ROADMAP.md and V0.8.0_SUMMARY.md.