📖 NCL Wavelet functionality

[anissa111]

Research existing NCL wavelet functionality, investigate existing python solutions, and make initial recommendations about reimplementation, wrapping, or writing equivalent workflow demonstration material

Relevant material:

• NCL wavelets
• wavelet analysis software that NCL used

[cyschneck]

Recommended guide for wavelet analysis: A Practical Guide to Wavelet Analysis by Christopher Torrence and Gilbert P. Compo (1998)

Additional resources:

• Wavelets: a mathematical microscope
• Wavelets and Multiresolution Analysis
• An introduction to the wavelet transform

[cyschneck]

NCL Function: wavelet

Calculates the wavelet transform of a time series and significance levels

Inputs:

• y: one-dimensional array
• mother: mother wavelet options (0="Morlet", 1="Paul", 2="DOG" (derivative of Gaussian))
• dt: amount of time between each y value (like sampling time)
• param: mother wavelet parameter
• s0: smallest scale of the wavelet
• dj: spacing between discrete scales
• jtot: integer number of scales
• npad: total number of points (including padding)
• noise: value of 0 for white noise background
• isigtest: value 0 is regular chi-square test from Eqn 18 from Torrence and Compo
• siglvl: significance level to use
• nadof: n/a (currently ignored)

Returns: Three-dimensional array (wave) dimensioned 2 by jtot by N

Wave attributes:

• power: one-dimensional array of length jtot*N containing squared sum of the real/imaginary parts of the wave
• phase: one-dimensional array of length jtot*N containing phases/degrees of wave
• mean: scalar containing the mean of the input series
• stdev: scalar containing std of input series
• lag1: scalar containing lag-1 auto correlation of input series
• r1: scalar with same type as wave
• dof one-dimensional array of length jtot containing degrees-of-freedom
• scale: one-dimensional array length jtot containing wavelet scales
• period: one-dimensional array of length jtot containing the Fourier periods
• gws: one-dimensional array of length jtot containing global wavelet spectrum
• coi: one-dimensional array length N containing e-folding factor
• fft_theor: one-dimensional array of length jtot containing theoretical red-noise spectrum
• signif: one-dimensional array of length jtot containing significance levels
• cdelta: scale containing constant Cdelta for mother wavelet
• psi: scalar containing constant psi(0) for mother wavelet

Possible Python implementation: PyWavlets

[cyschneck]

Pywavlet Relevant Wavelet families:

• Gaussian wavelets (gaus) -> Possible replacement for "DOG"
• Complex Gaussian wavelets (cgau) -> Possible replacement for "DOG"
• Morlet wavelet (morl)
• Complex Morlet wavelets

Additional Wavelet Types:

• Haar (haar)
• Daubechies (db)
• Symlets (sym)
• Coiflets (coif)
• Biorthogonal (bior)
• Reverse biorthogonal (rbio)
• “Discrete” FIR approximation of Meyer wavelet (dmey)
• Mexican hat wavelets (mexh)
• Shannon wavelets (shan)
• Frequency B-Spline wavelets (fbsp)

[cyschneck]

wavelets and pycwt are both more direct Python implementation of wavelets from Torrence and Compo that includes wavelets for Morlet, Paul, DOG (as well as Ricker, Marr, Mexican Hat)

While both are popular repositories with what appears to be clean implementation, both have either few or no releases, so would need to be re implemented to be compatible with Python 3.9-3.12+

[cyschneck]

pycwt appears to be the strongest replacement. Module based on C. Torrence and G. P. Compo paper

pycwt.cwt(signal, dt, dj=0.08333333333333333, s0=-1, J=-1, wavelet=u'morlet', freqs=None): Continuous wavelet transform of the signal at specified scales.

Input:

• signal: input signal array
• dt: sampling array
• dj: spacing between discrete scales
• s0: smallest scale of the wavelet
• j: number of scales less than one
• wavelet: mother wavelet class, defaults to Morlet
• freqs: custom frequencies

Returns:

• W: wavelet transform
• sj: Vector of scale
• freqs: vector of Fourier frequencies
• coi: Cone of influence
• fft: Normalized fast Fourier transform
• fftfreqs: Fourier frequencies for calculated FFT spectrum

[cyschneck]

Functionality includes:

• NCL 'wavelet': Power, Phase, and description for plotting
• NCL 'ShadeCOI': COI for NCL mother wavelets Morlet, Paul, and DOG