MODWTResult#

class cultivars.spectral.wavelets.MODWTResult(*, coefficients, scaling, details, smooth, variance, degrees_of_freedom, wavelet, nobs)[source]#

A MODWT decomposition: coefficients, additive components, and variance by scale.

The maximal-overlap transform keeps one coefficient per observation at every level, so level \(j\) is a zero-phase band-pass of the series onto periods \(2^j\) to \(2^{j+1}\) observations and the scaling coefficients \(V_J\) a low-pass onto everything longer. Two readings of the same coefficients are carried. The multiresolution analysis inverts each level alone to give details \(D_j\) and a smooth \(S_J\) that add back to the data exactly,

\[y_t = \sum_{j=1}^{J} D_{j,t} + S_{J,t},\]

each aligned in time with the series. The wavelet variance \(\hat\nu^2_j\) is the mean square of the level-\(j\) coefficients not touched by the periodic boundary, an unbiased estimate of the variance the series carries at that scale, with

\[\sum_{j=1}^{J} \nu^2_j + \operatorname{var}(S_J) \approx \sigma^2_y,\]

the analysis of variance by scale that the summary prints as shares. Each \(\hat\nu^2_j\) is approximately \(\nu^2_j \chi^2_{\eta_j}/\eta_j\) with \(\eta_j\) the equivalent degrees of freedom, which variance_interval() inverts.

Variables:

  • coefficients – (J, T) wavelet coefficients W_j, level by level; level j responds to periods of 2^j to 2^(j+1) observations.

  • scaling – (T,) level-J scaling coefficients V_J.

  • details – (J, T) multiresolution details D_j; with smooth they sum to the data exactly.

  • smooth – (T,) multiresolution smooth S_J, the part of the series at periods beyond 2^(J+1).

  • variance – (J,) unbiased wavelet variance per level; the levels’ sum plus the smooth’s variance is the series variance.

  • degrees_of_freedom – (J,) equivalent chi-squared degrees of freedom behind variance_interval().

  • wavelet – The filter used.

  • nobs – Observations.

Note

The transform is circular: the first \((2^j - 1)(L - 1)\) coefficients at level \(j\) (with \(L\) the filter length) wrap around to the end of the sample, and the details near either end inherit that. The variance excludes those coefficients, which is why its sum falls a little short of the series variance, and why the degrees of freedom shrink by roughly half per level: at the deepest level a 256-observation series under la8 leaves a single degree of freedom and a band that spans two orders of magnitude. The Percival-Walden \(\eta_3\) count used here is the conservative one and assumes the level is stationary; a deterministic trend loads on the smooth, not on any detail.

See also

  • MODWT – the producer.

  • WaveletCoherenceResult – the bivariate, continuous wavelet counterpart.

  • BandPassResult – the Fourier band-pass on a user-chosen band, where the wavelet’s bands are fixed at octaves.

References

Percival, D. B., & Walden, A. T. (2000). Wavelet Methods for Time Series Analysis, chapters 5 and 8. Cambridge University Press.

Example

>>> rng = np.random.default_rng(0)
>>> y = rng.standard_normal(256)
>>> res = MODWT(wavelet="haar", levels=3).transform(y)
>>> res.levels, res.periods
(3, ((2.0, 4.0), (4.0, 8.0), (8.0, 16.0)))
>>> bool(np.allclose(res.details.sum(axis=0) + res.smooth, y))
True

White noise puts half its variance in each successive octave, and the Haar level-1 coefficient is half the first difference:

>>> res.variance.round(2).tolist()
[0.49, 0.25, 0.14]
>>> bool(np.allclose(res.coefficients[0, 1:], np.diff(y) / 2))
True

A sinusoid of period 12 lands in the level whose band holds it:

>>> t = np.arange(1024.0)
>>> wave = MODWT(levels=5).transform(np.sin(2 * np.pi * t / 12))
>>> int(np.argmax(wave.variance)) + 1, wave.periods[int(np.argmax(wave.variance))]
(3, (8.0, 16.0))

Attributes#

coefficients

(J, T) wavelet coefficients by level.

scaling

(T,) level-J scaling coefficients.

details

(J, T) multiresolution details.

smooth

(T,) multiresolution smooth.

variance

(J,) unbiased wavelet variance per level; nan where no interior coefficient.

degrees_of_freedom

(J,) equivalent chi-squared degrees of freedom.

wavelet

"haar", "d4" or "la8".

nobs

Observations.

levels

Number of detail levels J.

periods

The band of periods, in observations, each level responds to.

scales

Physical scale 2^(j-1) of each level, in observations.

Methods#

summary()

The estimation summary, renderable as text, HTML, or a dataframe.

variance_interval([alpha])

Chi-squared confidence band for the wavelet variance at each level.