easyclimate.filter.wavelet

Wavelet transform

Functions

calc_timeseries_wavelet_transform(→ xarray.Dataset)

Wavelet transform parameters calculation.

draw_global_wavelet_spectrum(...[, ax, ...])

Draw global wavelet spectrum

draw_wavelet_transform(timeseries_wavelet_transform_result)

Draw wavelet transform

Module Contents

easyclimate.filter.wavelet.calc_timeseries_wavelet_transform(timeseries_data: xarray.DataArray, dt: float, time_dim: str = 'time', pad: float = 1, dj: float = 0.25, j1_n_div_dj: int = 7, s0=None, lag1: float = None, mother: str = 'morlet', mother_param=None, sigtest_wavelet: str = 'regular chi-square test', sigtest_global: str = 'time-average test', significance_level: float = 0.95) → xarray.Dataset

Wavelet transform parameters calculation.

Parameters

timeseries_data: xarray.DataArray.

Timeseries data.

dt: float.

Amount of time between each timeseries data value, i.e. the sampling time.

time_dim: str.

The time coordinate dimension name.

pad: float, default: 1.

if set to 1 (default is 0), pad time series with zeroes to get N up to the next higher power of 2. This prevents wraparound from the end of the time series to the beginning, and also speeds up the FFT’s used to do the wavelet transform. This will not eliminate all edge effects (see COI below).

dj: float, default: 0.25.

The spacing between discrete scales. A smaller dj will give better scale resolution, but be slower to plot.

j1_n_div_dj: int, default: 7.

Do j1_n_div_dj powers-of-two with dj sub-octaves each.

\[j1 = \mathrm{j1\underline{ }n\underline{ }div\underline{ }dj} / dj\]

This can adjust the size of the period.

s0: float, default: \(2 \times \mathrm{d}t\).

The smallest scale of the wavelet.

lag1: float, default: None.

Lag-1 autocorrelation for red noise background. The value is generated by statsmodels.api.tsa.acf.

mother: str, {‘morlet’, ‘paul’, ‘dog’}, default: ‘morlet’.

The mother wavelet function.

  • Name: Morlet (\(\omega_0\) = frequency)

  • \(\psi_0(\eta)\): \(\pi^{-1/4} e^{i \omega_{0} \eta} e^{-\eta^2/2}\).

  • Name: Paul (\(m\) = order)

  • \(\psi_0(\eta)\): \(\frac{2^m i^m m!}{\sqrt{\pi (2m)!}} (1-i \eta)^{-(m+1)}\).

  • Name: DOG (\(m\) = derivative)

  • \(\psi_0(\eta)\): \(\frac{(-1)^{m+1}}{\sqrt{\Gamma (m+\frac{1}{2})}} \frac{d^m}{d \eta^m} (e^{-\eta^2 /2})\).

mother_param: float.
The mother wavelet parameter.

  • For ‘morlet’ this is \(k_0\) (wavenumber), default is 6.

  • For ‘paul’ this is \(m\) (order), default is 4.

  • For ‘dog’ this is \(m\) (m-th derivative), default is 2.

sigtest_wavelet: {‘regular chi-square test’, ‘time-average test’, ‘scale-average test’}, default: ‘regular chi-square test’.

The type of significance test.

1. Regular chi-square test i.e. Eqn (18) from Torrence & Compo.

\[\frac{\left|W_n(s)\right|^2}{\sigma^2}\Longrightarrow\frac{1}{2} P_k\chi_2^2\]

  1. The “time-average” test, i.e. Eqn (23).

\[\nu=2\sqrt{1+\left(\frac{n_a\delta t}{\gamma s}\right)^2}\]

In this case, DOF should be set to NA, the number of local wavelet spectra that were averaged together. For the Global Wavelet Spectrum, this would be NA=N, where N is the number of points in your time series.

  1. The “scale-average” test, i.e. Eqns (25)-(28).

\[\overline{P}=S_{\mathrm{avg}}\sum_{j=j_1}^{j_2}\frac{P_j}{S_j}, \ \mathrm{where} \ S_{\mathrm{avg}}=\left(\sum_{j=j_1}^{j_2}\frac1{s_j}\right)^{-1}, \frac{C_\delta S_\mathrm{avg}}{\delta j\delta t\sigma^2}\overline{W}_n^2\Rightarrow\overline{P}\frac{\chi_\nu^2}\nu, \nu=\frac{2n_aS_{\mathrm{avg}}}{S_{\mathrm{mid}}}\sqrt{1+\left(\frac{n_a\delta j}{\delta j_0}\right)^2}.\]

In this case, DOF should be set to a two-element vector [S1,S2], which gives the scale range that was averaged together. e.g. if one scale-averaged scales between 2 and 8, then DOF=[2,8].

sigtest_global: {‘regular chi-square test’, ‘time-average test’, ‘scale-average test’}, default: ‘time-average test’.

See also the description of sigtest_wavelet.

significance_level: float, default: 0.95.

Significance level to use.

Returns

Timeseries wavelet transform result (xarray.Dataset).

See also

Reference

  • Torrence, C., & Compo, G. P. (1998). A Practical Guide to Wavelet Analysis. Bulletin of the American Meteorological Society, 79(1), 61-78. https://doi.org/10.1175/1520-0477(1998)079<0061:APGTWA>2.0.CO;2

  • Torrence, C., & Webster, P. J. (1999). Interdecadal Changes in the ENSO–Monsoon System. Journal of Climate, 12(8), 2679-2690. https://doi.org/10.1175/1520-0442(1999)012<2679:ICITEM>2.0.CO;2

  • Grinsted, A., Moore, J. C., and Jevrejeva, S.: Application of the cross wavelet transform and wavelet coherence to geophysical time series, Nonlin. Processes Geophys., 11, 561–566, https://doi.org/10.5194/npg-11-561-2004, 2004.

easyclimate.filter.wavelet.draw_global_wavelet_spectrum(timeseries_wavelet_transform_result: xarray.Dataset, ax: matplotlib.axes.Axes = None, global_ws_kwargs: dict = {}, global_signif_kwargs: dict = {'ls': '--'})

Draw global wavelet spectrum

Parameters

timeseries_wavelet_transform_result: xarray.Dataset.

Timeseries wavelet transform result.

ax: matplotlib.axes.Axes

The axes to which the boundary will be applied.

**global_ws_kwargs, dict, optional:

Additional keyword arguments to xarray.DataArray.plot.line for ploting global_ws.

**global_signif_kwargs, dict, optional, default {‘ls’: ‘–‘}:

Additional keyword arguments to xarray.DataArray.plot.line for ploting global_signif.

easyclimate.filter.wavelet.draw_wavelet_transform(timeseries_wavelet_transform_result: xarray.Dataset, ax: matplotlib.axes.Axes = None, power_kwargs: dict = {'levels': [0, 0.5, 1, 2, 4, 999], 'colors': ['white', 'bisque', 'orange', 'orangered', 'darkred']}, sig_kwargs: dict = {'levels': [-99, 1], 'colors': 'k'}, coi_kwargs: dict = {'color': 'k'}, fill_between_kwargs: dict = {'facecolor': 'none', 'edgecolor': '#00000040', 'hatch': 'x'})

Draw wavelet transform

Parameters

timeseries_wavelet_transform_result: xarray.Dataset.

Timeseries wavelet transform result.

axmatplotlib.axes.Axes

The axes to which the boundary will be applied.

**power_kwargs, optional, dict, default {‘levels’: [0, 0.5, 1, 2, 4, 999], ‘colors’: [‘white’, ‘bisque’, ‘orange’, ‘orangered’, ‘darkred’]}:

Additional keyword arguments to xarray.DataArray.plot.contourf for ploting power.

**sig_kwargs, optional, dict, default {‘levels’: [-99, 1], ‘colors’: ‘k’}:

Additional keyword arguments to xarray.DataArray.plot.contourf for ploting sig.

**coi_kwargs, optional, dict, default {‘color’: ‘k’}:

Additional keyword arguments to xarray.DataArray.plot.contourf for ploting coi.

**fill_between_kwargs, dict, optional, default {‘facecolor’: ‘none’, ‘edgecolor’: ‘#00000040’, ‘hatch’: ‘x’}:

Additional keyword arguments to matplotlib.pyplot.fill_between.