[Feature]: Wavelet transforms

[gabyfle]

Initial Checklist

• I have searched the existing issues to ensure this feature has not already been requested.

Problem Statement & User Value

As a DSP engineer, I need to perform high-resolution time-frequency analysis on non-stationary signals to identify and characterize transient events.

Acceptance Criteria (Definition of Done)

• Public API Definition
  • Implementation must be done in the SoundML.Transform module.
  • The Continuous Wavelet Transform (CWT) is implemented with the following public function signature in SoundML.Transform:
• Supported Mother Wavelets
  • The implementation must support the following minimum set of mother wavelets, with properties and applications as described:

Transform	Family	Name(s)	Key Characteristics	Common Applications
CWT	Morlet	Morlet	Analytic (Complex), Non-orthogonal	Time-frequency analysis of non-stationary signals like neuro-electrical data, music, and machinery vibrations.
CWT	Mexican Hat	MexicanHat	Real, Non-orthogonal, 2nd derivative of Gaussian	Detection of localized, isotropic features like point sources in astrophysical maps or other blob-like structures.
DWT	Haar	Haar / Db 1	Orthogonal, Compact Support, Discontinuous	Simple, fast transform; good for detecting step-discontinuities. Used in compression and feature extraction.
DWT	Daubechies	Db 2 - Db 10	Orthogonal, Compact Support, Asymmetric	Workhorse for DWT. Higher orders are smoother. Excellent for compression and denoising of a wide range of signals.
DWT	Symlets	Sym 2 - Sym 8	Near Symmetric version of Daubechies, Orthogonal	Similar to Daubechies but with increased symmetry, which can reduce artifacts at signal boundaries. Good for feature detection.

• Output Data Structures
  • All numerical inputs and outputs must use Rune.t.
  • CWT coefficients output must be a 2D array of complex floats (Complex64).
  • DWT wavedec output must be a Rune.t, with each element being a 1D array of floats (Float64).
• Error Handling
  • The implementation must raise specific, documented exceptions for invalid inputs.
  • Runtime checks must be in place for:
    • Input data being a 1D Rune.t.
    • Minimum signal length requirements.
    • Scales for CWT being positive and monotonically increasing.
    • Level for DWT being a non-negative integer within a valid range.
    • Signal length compatibility with the chosen DWT level (e.g., length must be a multiple of $2^{level}$ for some modes).
• Unit Testing
  • A comprehensive test suite must be added in the test/ directory.
  • Tests must cover every supported mother wavelet for both CWT and DWT.
  • Tests must include edge cases: empty input, very short signals, single-point signals, and invalid parameter values.
  • Numerical correctness must be verified by comparing output against known values from a gold-standard reference implementation (e.g., PyWavelets) with a reasonable tolerance.
  • The DWT/IDWT round trip must reconstruct the original signal near-perfectly (within floating-point error).
• Documentation
  • The public API must be fully documented.
  • Each function's documentation must clearly describe its purpose, all parameters, the return value, and any exceptions it may raise.

Proposed Solution or Technical Approach (Optional)

• Wavelet Representation: A record will be defined for each wavelet family to store its properties. For DWT wavelets (e.g., Daubechies), this record will contain the low-pass and high-pass decomposition and reconstruction filter coefficients, stored as Rune.t arrays. For CWT wavelets, the record will contain the parameters needed to generate the wavelet function at any given scale.

Additional Context (Mockups, Links, etc.)

No response

References

• Mallat, S. (2009). A Wavelet Tour of Signal Processing: The Sparse Way. Academic Press.
• PyWavelets Documentation: https://pywavelets.readthedocs.io/en/latest/
• MATLAB Wavelet Toolbox Documentation: https://www.mathworks.com/help/wavelet/
• SciPy Signal Processing (scipy.signal.cwt): https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.cwt.html

Code of Conduct

• I agree to follow this project's Code of Conduct.