WaveletCoherenceResult#

class cultivars.spectral.wavelets.WaveletCoherenceResult(*, coherence, phase, scales, periods, cone, significance, alpha, omega0, nobs)[source]#

Squared wavelet coherence and phase of two series over scale and time.

With \(W_x(s, t)\) and \(W_y(s, t)\) the Morlet transforms and \(W_{xy} = W_x \overline{W_y}\) the cross-wavelet, the squared coherence is the smoothed, normalized cross-power

\[R^2(s, t) = \frac{\bigl|S\bigl(W_{xy}(s, t)/s\bigr)\bigr|^2} {S\bigl(|W_x(s, t)|^2/s\bigr)\, S\bigl(|W_y(s, t)|^2/s\bigr)},\]

a local \(R^2\) between the two series at scale \(s\) and date \(t\), and the phase difference \(\phi(s, t) = \arg S(W_{xy})\) their local lead-lag, positive when the first series leads. \(S\) is the Torrence-Webster smoothing (Gaussian in time with width \(s\), boxcar over 0.6 octave in scale) without which \(R^2 \equiv 1\). The scale axis is converted to Fourier periods by \(\lambda = 4\pi s / (\omega_0 + \sqrt{2 + \omega_0^2})\), 1.03 at \(\omega_0 = 6\); the cone of influence marks coefficients within \(\sqrt 2\, s\) of either edge, where the zero padding behind the transform is felt; and the significance level is the \(1 - \alpha\) quantile of the coherence of independent AR(1) surrogates, scale by scale, because smoothed coherence is high in places by chance and must be read against that, not against zero.

Variables:

  • coherence – (S, T) squared coherence in [0, 1].

  • phase – (S, T) phase difference in radians, arg(W_xy); positive means the first series leads at that scale.

  • scales – (S,) wavelet scales, in observations.

  • periods – (S,) equivalent Fourier periods.

  • cone – (S, T) flags, True where the coefficient lies inside the cone of influence and edge padding contaminates it.

  • significance – (S,) per-scale coherence level exceeded with probability alpha by independent AR(1) surrogates, or None when no surrogates were run.

  • alpha – Level behind significance.

  • omega0 – Morlet centre frequency.

  • nobs – Observations.

Note

Phase is meaningful only where coherence is: the lead-lag of two series that do not comove at a scale is the argument of a noisy complex number, and the summary’s lead column is printed for every octave regardless. Read it alongside the share significant column, and prefer lead() over a band you have already seen to be coherent. The largest scales reach the sample length, so their cone covers every date and their significance is nan; significant() is False there and lead() returns nan for a band with no date outside the cone.

See also

References

Torrence, C., & Compo, G. P. (1998). A practical guide to wavelet analysis. Bulletin of the American Meteorological Society, 79(1), 61-78.

Grinsted, A., Moore, J. C., & Jevrejeva, S. (2004). Application of the cross wavelet transform and wavelet coherence to geophysical time series. Nonlinear Processes in Geophysics, 11, 561-566.

Example

Two noisy copies of a period-24 sinusoid, the second delayed by three observations: coherence is significant in the band holding the signal and not at short periods, and the lead is about three:

>>> rng = np.random.default_rng(0)
>>> t = np.arange(256.0)
>>> signal = np.sin(2 * np.pi * t / 24)
>>> x = signal + 0.5 * rng.standard_normal(256)
>>> y = np.roll(signal, 3) + 0.5 * rng.standard_normal(256)
>>> res = WaveletCoherence(per_octave=4, surrogates=100, seed=1).compute(x, y)
>>> res.coherence.shape, res.scales.shape, res.nobs
((29, 256), (29,), 256)
>>> hit = res.significant()
>>> band = (res.periods > 20) & (res.periods < 30)
>>> bool(hit[band].mean() > 0.5), bool(hit[res.periods < 8].mean() < 0.15)
(True, True)
>>> bool(2.0 < res.lead((20.0, 30.0)) < 4.5)
True

Attributes#

coherence

(S, T) squared coherence.

phase

(S, T) phase difference in radians.

scales

(S,) wavelet scales in observations.

periods

(S,) equivalent Fourier periods.

cone

(S, T) cone-of-influence flags.

significance

(S,) surrogate significance level, or None.

alpha

Level behind significance.

omega0

Morlet centre frequency.

nobs

Observations.

Methods#

lead(scale_band)

Mean lead of the first series, in observations, over a band of periods.

significant()

Where coherence exceeds the surrogate level, outside the cone of influence.

summary()

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