*! version 1.1.0 2026-05-11

Title

wtc -- Wavelet Coherence with Monte-Carlo significance

Syntax

wtc var1 var2 [if] [in],
[dt(#) mother(name) param(#) dj(#)
s0(#) nrands(#) plot colormap(name) nodisplay]

Description

wtc computes wavelet coherence between two time series. Coherence
is the localized correlation in the time-frequency plane:

R²(s,t) = |S(s^-1 W_xy)|² / [S(s^-1 |W_x|²) * S(s^-1 |W_y|²)]

where S is a smoothing operator (Gaussian in time, boxcar in scale)
following Torrence & Webster (1999). Statistical significance is tested
via Monte Carlo simulation against AR(1) surrogate pairs (default
nrands(300)).

The CWT pre-processing applies a 5% cosine taper plus anti-symmetric
edge reflection before the FFT, eliminating the high-frequency ringing
artefacts that produce streaks in zero-padded implementations.

Options

dt(#) time step (default 1)

mother(name) mother wavelet: morlet (default),
paul, dog

param(#) mother-specific parameter (-1 = use mother's
default: 6 for morlet, 4 for paul, 2 for dog)

dj(#) scale spacing in sub-octaves (default 0.25)

s0(#) smallest scale (default 2*dt)

nrands(#) number of Monte Carlo surrogates (default 300).
Set higher (1000+) for tight publication confidence intervals; lower
(50-100) for fast exploration

plot produce a Grinsted-style coherence heatmap with:
log-period y-axis, dashed cone-of-influence line, phase arrows
(drawn where R² > 0.5), and a 2-D smoothing/median display filter

colormap(name) heatmap colormap: jet (default,
matches Grinsted toolbox), parula, turbo

nodisplay suppress the text results table

Phase-arrow convention

Arrows are sub-sampled across the time/scale grid; direction encodes
the phase of W_xy at that point:

> in-phase (var1 and var2 move together)

< anti-phase (move opposite)

^ var1 leads var2 by 1/4 cycle

v var2 leads var1 by 1/4 cycle

Examples

. wtc gdp inflation, dt(0.25) plot

. wtc gdp inflation, nrands(1000) plot colormap(parula)

Stored results

Scalars

e(N) number of observations

e(dt) time step

e(nrands) Monte Carlo surrogate count

Macros

e(cmd) wtc

e(var1) e(var2) variable names

e(mother) mother wavelet used

Matrices

e(rsq) coherence R² (nscale x N)

e(phase) phase difference in radians (nscale x N)

e(signif) MC significance threshold per scale (nscale x 1)

e(period) Fourier period vector

e(scale) wavelet scale vector

e(coi) cone-of-influence period at each time (N x 1)

References

Grinsted, A., Moore, J.C., Jevrejeva, S. (2004). Application of
the cross wavelet transform and wavelet coherence to geophysical time
series. Nonlin. Proc. Geophys. 11: 561-566.

Torrence, C., Webster, P.J. (1999). Interdecadal changes in the
ENSO-monsoon system. J. Climate 12: 2679-2690.

Also see

wavelet, wt, xwt