Module coherence 

Wavelet Coherence Module

Provides time-frequency coherence analysis between two signals using continuous wavelet transforms. Wavelet coherence reveals the degree of correlation between signals at different scales (frequencies) and times.

Mathematical Background

Wavelet coherence is defined as:

R²(a,b) = |S(a⁻¹ W_xy(a,b))|² / (S(a⁻¹ |W_x(a,b)|²) · S(a⁻¹ |W_y(a,b)|²))

where:

• W_x, W_y: CWT of signals x and y
• W_xy: Cross-wavelet transform (W_x · W_y*)
• S: Smoothing operator (in time and scale)
• a: scale parameter
• b: time parameter

The result is bounded between 0 and 1, similar to correlation coefficient.

Performance Optimizations

This module implements several optimizations for efficient coherence computation:

• Pre-computed Weight Matrix: Scale smoothing weights are computed once and reused, eliminating redundant computations across time points
• Sparse Windowing: Only weights within 3σ are stored and computed, reducing complexity from O(n²) to O(n × window_size) for large scale arrays
• Parallel Processing: Smoothing operations are parallelized using Rayon, leveraging multi-core CPUs for significant speedup

These optimizations provide:

• ~2-4x speedup for typical use cases (30-50 scales)
• ~10-20x speedup for large scale arrays (100+ scales)
• O(n × window_size) complexity instead of O(n²) for scale smoothing

Applications

• Finance: Cross-asset correlation dynamics, pairs trading
• Climate: Relationships between climate signals
• Neuroscience: Brain signal coherence analysis
• Engineering: Multi-sensor system correlation

See Also

• High-level user guide: docs/USER_GUIDE.md
• Advanced analysis overview (coherence, matching pursuit, multifractal): docs/ADVANCED_ANALYSIS.md
• Transform behavior and trade-offs (CWT vs others): docs/TRANSFORMS_GUIDE.md

Example

use iron_wave::analysis::coherence;
use iron_wave::transform::complex_wavelets::ComplexMorlet;
use iron_wave::signal::Signal;

// Simple synthetic signals (identical for high coherence)
let signal1 = Signal::new(vec![1.0, 2.0, 3.0, 4.0]);
let signal2 = Signal::new(vec![1.0, 2.0, 3.0, 4.0]);
let wavelet = ComplexMorlet::new(6.0, 1.0);
let scales: Vec<f64> = (1..4).map(|i| i as f64).collect();

let result = coherence::wavelet_coherence(
    &signal1,
    &signal2,
    &wavelet,
    &scales,
    1.0, // sampling frequency
    None,
)?;

// Analyze coherence at specific scale
let coh_at_scale_1 = &result.coherence[0];
assert_eq!(coh_at_scale_1.len(), signal1.len());

Structs

CoherenceConfig

Configuration for wavelet coherence computation

CoherenceResult

Result of wavelet coherence computation

CrossSpectrumResult

Result of cross-wavelet spectrum computation

Functions

cross_wavelet_spectrum

Compute cross-wavelet spectrum only (without full coherence)

wavelet_coherence

Compute wavelet coherence between two signals