Skip to main content

IronWave User Guide (High-Level)

IronWave provides production-grade wavelet transforms and related tools for quantitative finance and general signal processing. This guide focuses on how to choose and use the right components rather than on API details (see README.md and docs.rs for full API reference).

Use this guide as an orientation map:

  • Which wavelet family to pick.
  • Which transform (DWT, MODWT, SWT, WPT, CWT, EMD/EEMD) fits your problem.
  • How to think about advanced analysis (coherence, matching pursuit, multifractal).
  • When to use batch vs streaming.

For deeper mathematical and implementation details see:

  • docs/WAVELET_FAMILIES.md
  • docs/TRANSFORMS_GUIDE.md
  • docs/ADVANCED_ANALYSIS.md
  • MATHEMATICAL_VALIDATION.md
  • STREAMING_SUPPORT.md

1. Typical Workflows​

Most IronWave workflows follow a few common patterns.

1.1 Multi-scale decomposition and denoising​

Goal: separate a signal into coarse and fine scales, remove noise, and optionally reconstruct.

Typical steps:

  • Choose a wavelet (e.g., Db4, Sym4) and transform:
    • Financial time series: MODWT or SWT for shift-invariance.
    • General signals / compression: DWT.
  • Decide on:
    • Number of levels (e.g., 3–6 depending on length and desired coarseness).
    • Boundary mode (often Periodic for finance; Symmetric for more “natural” boundaries).
  • Compute transform, optionally apply thresholding, and reconstruct if needed.

Relevant APIs:

  • modwt_multilevel, imodwt_multilevel
  • dwt, idwt
  • Financial helpers such as denoise_modwt.

1.2 Time–frequency analysis​

Goal: understand how frequency content changes over time.

Typical steps:

  • Use CWT with a complex wavelet (usually Morlet).
  • Select a scale/frequency grid (log-spaced or application-specific).
  • Visualize magnitude or power as a scalogram.

Relevant APIs:

  • transform::cwt / cwt_fft
  • transform::complex_wavelets::{ComplexMorlet, ComplexMexicanHat, ComplexPaul}
  • analysis::coherence::wavelet_coherence (for cross-signal analysis).

1.3 Advanced cross-signal and structure analysis​

Goal: go beyond single-signal transforms to relationships and scaling structure.

  • Wavelet coherence – time–frequency correlation between two signals.
  • Matching Pursuit / OMP – sparse decomposition into wavelet atoms.
  • Multifractal analysis – Hurst exponent and multifractal spectrum (via wavelet leaders).

Relevant APIs:

  • analysis::coherence::*
  • decomposition::matching_pursuit::*
  • analysis::multifractal::*

2. Choosing a Wavelet​

Detailed recommendations are in docs/WAVELET_FAMILIES.md; this section gives short, practical defaults.

2.1 Quick recommendations​

  • Haar

    • Good for: jump detection, microstructure effects, piecewise-constant signals.
    • Pros: fastest, minimal support, excellent at capturing discontinuities.
    • Cons: poor frequency localization, blocky reconstructions.

  • Daubechies (Db2, Db4, Db6, Db8)

    • Db4 is the default workhorse for finance and many general tasks.
    • More taps → smoother, better frequency localization but larger support and more edge effects.
    • Use Db2/Db4 for shorter signals and real-time work; Db6/Db8 for smoother signals and offline analysis.

  • Symlets (Sym2, Sym4, Sym6)

    • More symmetric versions of Daubechies; reduce phase distortion.
    • Good for: trend analysis, where symmetry and phase are important.

  • Coiflets (Coif1, Coif2)

    • More vanishing moments; good at polynomial detrending.
    • Good for: removing smooth trends and working with slowly varying baselines.

  • Biorthogonal (CDF 5/3, CDF 9/7)

    • Implemented via lifting; useful where reversible transforms or JPEG2000-style behavior matter.
    • More common in image/compression work than in finance.

2.2 How to choose in practice​

  • Financial time series

    • Volatility estimation / regime detection: Db4 or Sym4 + MODWT.
    • Jump detection at high frequency: Haar + DWT or MODWT.
    • Long-horizon trends: Sym4 or Coif1 + MODWT or SWT.

  • General 1D signals

    • If uncertain, start with Db4; try Sym4 if you care about phase/symmetry.
    • For very short signals or tight latency budgets, Haar or Db2 often works well.

3. Choosing a Transform​

See docs/TRANSFORMS_GUIDE.md for a deep dive; here is a quick matrix.

3.1 Discrete transforms​

  • DWT (Discrete Wavelet Transform)

    • Pros: fast, downsampling saves memory and CPU.
    • Cons: shift-variant; sensitive to boundary handling, especially with non-periodic modes.
    • Use when: you want compact representations or compression and can tolerate shift variance.

  • MODWT (Maximal Overlap DWT)

    • Pros: shift-invariant, works for any length, perfect reconstruction with all boundaries.
    • Cons: more computation than DWT; redundancy factor ≈ number of levels.
    • Use when: analyzing time series (especially finance), estimating volatility, doing scaling analysis.

  • SWT (Stationary Wavelet Transform)

    • Pros: shift-invariant, redundant; good for denoising where alignment matters.
    • Cons: more redundant than MODWT; can be heavier for many levels.
    • Use when: you want redundancy for denoising and are not as concerned with redundancy cost.

  • WPT (Wavelet Packet Transform)

    • Pros: adaptive frequency tiling; good for microstructure and detailed frequency analysis.
    • Cons: more complex; best-basis selection requires care.
    • Use when: you need detailed frequency partitioning beyond standard octave bands.

3.2 Continuous and adaptive transforms​

  • CWT (Continuous Wavelet Transform)

    • Pros: rich time–frequency picture, especially with complex wavelets.
    • Cons: heavier than DWT/MODWT; edge effects; more tuning (scales, wavelet parameters).
    • Use when: you need time–frequency visualization or wavelet coherence.

  • Dual-tree CWT

    • Pros: improved directional/selective behavior for complex-valued analysis.
    • Use when: phase/direction matters, especially in 2D / multicomponent signals.

  • EMD / EEMD

    • Pros: fully adaptive, no preset basis; excels on non-stationary, nonlinear signals.
    • Cons: computationally heavier; not streamable; interpretation can be trickier.
    • Use when: you need empirical modes and instantaneous frequency (e.g., Hilbert–Huang analysis).

4. Advanced Features at a Glance​

These are covered in depth in docs/ADVANCED_ANALYSIS.md.

4.1 Wavelet coherence​

What it does:

  • Measures time–frequency coherence between two signals.
  • Uses CWT-based cross-spectrum and Gaussian smoothing in time and log-scale.

Good for:

  • Cross-asset correlation and lead/lag in finance.
  • Multisensor and climate signal relationships.

Recommended starting points:

  • Wavelet: ComplexMorlet::new(6.0, 1.0).
  • Scales: logarithmic or linear grid covering your band of interest (e.g., 1–64).
  • Smoothing: use the default CoherenceConfig unless you see excessive noise or oversmoothing.

4.2 Matching Pursuit / Orthogonal Matching Pursuit​

What it does:

  • Represents a signal as a sparse combination of precomputed wavelet atoms.
  • MP: greedy, simple; OMP: greedier but orthogonalized residual, better convergence.

Good for:

  • Sparse factor extraction from returns.
  • Feature extraction, compression, or pattern discovery.

Recommended starting points:

  • Dictionary: Db4 + Haar, up to 3–5 scales for signals up to a few thousand samples.
  • Iterations: 10–50, or until residual energy stops improving significantly.
  • Prefer OMP when you care about reconstruction quality; MP suffices for a quick sparse sketch.

4.3 Multifractal analysis (wavelet leaders)​

What it does:

  • Estimates Hurst exponent (long-range dependence) and multifractal spectrum via wavelet leaders.

Good for:

  • Volatility persistence and market efficiency analysis.
  • Any system where scaling and local regularity matter (climate, hydrology, turbulence).

Recommended starting points:

  • Wavelet: Db2 or Db4.
  • Moments: q from −2 to 2 in steps of 0.5 (the default range is usually reasonable).
  • Scales: skip the finest scale by default (more robust to noise/boundaries).

5. Batch vs Streaming​

5.1 When to use streaming​

Use streaming transforms when:

  • You process tick-by-tick or high-frequency data in real time.
  • Latency and bounded memory are critical.

Supported streaming transforms:

  • StreamingDWT, StreamingMODWT, StreamingSWT.
  • Built on a ring buffer, with configurable window sizes and update triggers.
  • Higher-level streaming tools: streaming denoiser, jump detector, regime detector.

See STREAMING_SUPPORT.md for details and capabilities.

5.2 When batch is enough​

Use batch transforms when:

  • You analyze historical data / windows of data.
  • You need CWT, WPT, or EMD/EEMD.
  • You can afford to recompute on each analysis window.

6. Where to Go Next​

  • For wavelet-specific guidance (Haar vs Db4 vs Sym4, etc.), read docs/WAVELET_FAMILIES.md.
  • For transform-specific behavior and trade-offs (DWT vs MODWT vs CWT vs EMD), see docs/TRANSFORMS_GUIDE.md.
  • For coherence, matching pursuit, multifractal, and streaming analytics, see docs/ADVANCED_ANALYSIS.md and STREAMING_SUPPORT.md.
  • For mathematical guarantees and test coverage, see MATHEMATICAL_VALIDATION.md.