ASToolbox Quick Guide

(version released in April 2018)

Luı́s Aguiar-Conraria∗ Maria Joana Soares†

April 12, 2018

This is a brief description of the main features of the version of the ASToolbox released in
April 2018.
The main difference from previous versions is the possibility of computing the wavelet
gain/partial gain. We also made it totally independent of other Matlab toolboxes (i.e. there
is no need of the Econometrics Toolbox, Statistics Toolbox or Signal Processing Toolbox) and
introduced some simplifications, dictated by the experience on the use of the previous versions.
A more detailed explanation of the functionalities of ASToolbox can be seen in the appendix
of reference [1]; for the wavelet gain see [2] and [3].
Some of our functions are based on functions written by Christopher Torrence and Gilbert
P. Compo (http://paos.colorado.edu/research/wavelets/) and on functions written by Bernard
Cazelles and Mario Chavez; [4].

1 Structure
The folder ASToolbox is divided into two sub-folders:

1. Functions – containing all the Matlab functions. This has two sub-folders:

(a) Auxiliary – containing some auxiliary functions to, e.g. generate surrogate series or
compute Fourier spectra; it also contains a function to compute measures associated
with the generalized Morse wavelets.
(b) WaveletTransforms – containing functions to compute the (analytic) wavelet trans-
form, cross-wavelet transform, wavelet coherency, wavelet gain, wavelet phase-difference,
wavelet multiple/partial coherency, wavelet partial phase-difference and wavelet par-
tial gain.
∗
NIPE and Economics Department, University of Minho. E-mail: lfaguiar@eeg.uminho.pt
†
NIPE and Department of Mathematics and Applications, University of Minho. E-mail:
jsoares@math.uminho.pt

1
 2. Examples – containing four Matlab scripts illustrating the use of the main functions
contained in the toolbox; the data and codes to generate the pictures in references [2]
and [3] are also provided.

Main differences form older versions of the toolbox:

• Functions AWCO and MPAWCO were replaced by AWCOG and MPAWCOG, respectively,
which allow wavelet gain computations.

• Functions AWCOOutput, AWCOOutputV2, AWTOutput, AWTOutputV2, MPAWCOOutput

and MPAWCOOutputV2 were eliminated and new functions MeanPHASE and MeanGAIN
were introduced.

• Functions SurrogateARMABoot and SurrogateARMAEcon used to construct surrogates

of a given series were replaced by a new function SurrogateSeries, independent of the
Econometrics toolbox.

• Was written with MATLAB Version: 9.0.0.341360 (R2016a).

2 Brief description of the functions in folder Functions

More details on how to use each of the functions are given in the function code.

2.1 Folder Auxiliary

1. ARMA2SR
Fits an ARMA(p, q) model to a given series, using a two-step linear regression.

2. AROLS
Fits an AR(p) model to a given series, using Ordinary Least Squares.

3. ChiSquareCDF
Computes the chi-square cumulative distribution function.

4. FourierSpectrum
Estimates the Fourier spectrum of a series.

5. GMWMeasures
Computes several quantities associated with a generalized Morse wavelet.

6. MatrixMax
Calculates the location of the local maxima of a given matrix.

2
 7. ProcessMatrix
Processes (takes log and/or normalizes) the columns of a given matrix.

8. SurrogateSeries
Generates surrogate series of a given time-series. The surrogates are obtained by adjusting
to the series an ARMA(p, q) model (making use the function ARMA2SR) and constructing
new samples by drawing errors from a Gaussian distribution. This function needs no
function from the Matlab Econometrics toolbox.1

9. WaveletCoSpectra
Computes the complex wavelet coherencies of several series given as columns of two
matrices. These are saved in a cell-array.

10. WaveletSpectra
Computes the wavelet spectra (i.e. wavelet transforms) of several series given as columns
of a matrix. These are saved in a cell-array.

2.2 Folder WaveletTransforms

1. AWCOG (Analytical Wavelet COherency and Gain)
Computes the (matrix of the) complex wavelet coherency of two series, using analytic
wavelet transforms with a Morlet or a generalized Morse wavelet. Smoothing in coherency
computation is done by convolution with Hamming windows.2
May also compute the (matrix of normalized) cross-wavelet transform and the (matrix)
of complex wavelet gain.
It can also give the p-values for the wavelet coherency. To compute these p-values, it
makes use of the function SurrogateSeries contained in the folder Auxiliary.
Main differences from the analogous function AWCO in older versions of the toolbox:

(a) It allows the computation of the (complex) wavelet gain.

1
In a first version, we had as an option the possibility of using the functions arima, estimate and simulate
of the Matlab Econometrics toolbox to construct the surrogates; many experiments conducted led us to the
conclusion that, although the coefficients of the ARMA(p, q) model computed with the function ARMA2SR do
not always agree with the coefficients obtained with the use of the functions arima and estimate, our surrogate
series turn out to be indistinguishable from the ones computed with the Econometrics toolbox, so we decided
to use only our own functions.
2
From our experience, the type of window used — Bartlett, Box, Hamming, Hanning or Triangular (which
were the options in the previous versions of the toolbox) — plays no significant role in the coherency compu-
tations (the size of the window being more relevant); for this reason, we decided to fix the type of window to
simplify the use of the toolbox.

3
 (b) It allows the use of other type of boundary conditions when computing the wavelet
transforms (not-only zero-pad, but also reflection at the boundaries or repetition of
first and last element of the series).
(c) One can use either 0 or [ ] to indicate default values as inputs.
(d) Only the vector of periods (and not scales) is an output (have to be careful with the
number and order of outputs!).
(e) Hamming windows are used for smoothing in coherency computation (i.e. there is
no choice of type of windows).
(f) Smoothed cross is not a possible output.
(g) The cross wavelet transform is normalized, to avoid the bias effect; see [7].
(h) Because of the gain computation, the series are not normalized (we simply subtract
the mean, but do not divide by the standard deviation).

2. AWT (Analytical Wavelet Transform)

Computes the (matrix of the) analytic wavelet transform of a given series, using a Morlet
or a generalized Morse wavelet. It can also compute the (matrix of the normalized)
wavelet power spectrum and the corresponding p-values. To compute the p-values, if a
Morlet wavelet is selected and an AR(0) or AR(1) process is used as the null, theoretical
distributions may be used (this is much faster); otherwise, the p-values are computed
using Monte-Carlo simulations; in this case, it makes use of the function SurrogateSeries
contained in the folder Auxiliary.
Main differences from the older versions:

(a) It allows the use of other type of boundary conditions when computing the wavelet
transform (not-only zero-pad, but also reflection at the boundaries or repetition of
first and last element of the series).
(b) One can use either 0 or [ ] to indicate default values as inputs.
(c) Only the vector of periods (and not scales) is an output.
(d) The wavelet power is normalized, to avoid the bias effect; see [5].

3. MeanGAIN
Computes the mean wavelet gain or mean partial wavelet gain corresponding to a given
frequency band. The mean is computed as the absolute value of the mean of the complex
gains or complex partial wavelet gains associated with the given frequency band.

4
4. MeanPHASE
Computes the mean phase (mean phase-difference or mean partial phase-difference) cor-
responding to a given frequency band. Confidence interval for the means can also be
computed. The mean is computed as the circular mean of the phases (phase-differences
or partial phase-differences) associated with the given frequency gain. Main difference
from corresponding outputs obtained with functions AWTOutputV2, AWCOOutputV2 and
MPAWCOOutputV2 in older versions of the toolbox:

(a) In the referred functions, the mean was obtained as the angle of the mean of the
(complex) wavelet transform values (or coherencies or partial wavelet coherencies),
i.e. as a kind of “weighted” circular mean; we now use the exact circular mean (see,
e.g. [8]).
(b) Confidence intervals for the mean can also be computed.

5. MPAWCOG (Multiple and Partial Analytical Wavelet COherency and Gain)

Computes (matrix of) multiple wavelet coherency and/or (matrix of) complex partial
wavelet coherency of several series, given as columns of a matrix. These are computed
using analytic wavelet transforms, with a Morlet or a generalized Morse wavelet. Smooth-
ing in coherency computations is done by convolution with Hamming windows.
It can also compute the corresponding p-values. The p-values are computed using Monte-
Carlo simulations making use of the function SurrogateSeries described above.
It can also compute the (matrix of complex) wavelet partial gain.
Main differences from the analogous MPAWCO:

(a) It allows the computation of the complex partial wavelet gain.

(b) It allows the use of other type of boundary conditions when computing the wavelet
transforms (not-only zero-pad, but also reflection at the boundaries or repetition of
first and last element of the series).
(c) One can use either 0 or [ ] to indicate default values as inputs.
(d) Only the vector of periods (and not scales) is an output.
(e) Hamming windows are used for smoothing, when computing coherencies (i.e. there
is no choice of type of windows).

5
3 Brief description of the scripts in the folder Examples
1. Example1 Power
Illustrates the use of AWT (wavelet power computation). It also makes use of the auxil-
iary functions FourierSpectrum and MatrixMax. Produces a picture similar to the one in
Example 1 in [1].

2. Example2 Coherency
Illustrates the use of the functions AWCOG (coherency computations) and MeanPHASE.
Generates a picture similar to the one in Example 2 in [1].

3. Example3 MultPartCoher
Illustrates the use of the functions MPAWCOG (multiple and partial coherencies com-
putations) and MeanPHASE. Generates a picture similar to the one in Example 3 in
[1].

4. Example4 Gains
Illustrates the use of the functions MPAWCOG (multiple, partial coherencies and gain
computations), MeanPHASE and MeanGAIN. Generates a picture similar to Figure 1 in
[3].

In this folder, you can also find two sub-folders — DataCodes NIPE WP 13 2017 and Data-
Codes NIPE WP 04 2018 with the data and codes to generate the pictures in references [2] and
[3], respectively.

References
[1] Aguiar-Conraria, L., and Soares, M. J. (2014) The continuous wavelet transform: moving
beyond uni-and bivariate analysis. Journal of Economic Surveys, 28, 344–375.

[2] Aguiar-Conraria, L., Soares, M. J. and Sousa, R. (2017) California’s Carbon Market and
Energy Prices: A Wavelet Analysis, NIPE Working Papers, University of Minho, NIPE
WP 13/2017 (submitted for publication)

[3] Aguiar-Conraria, L., Martins, M. M. and Soares, M. J. (2018) Estimating the Taylor Rule
in the time-frequency domain, NIPE Working Papers, University of Minho, NIPE WP
04/2018 (submitted for publication)

[4] Cazelles, B., Chavez, M., Magny, G., Guégan, J-F and Hales, S. (2007), Time-dependent
spectral analysis of epidemiological time-series with wavelets. Journal of the Royal Society
Interface 4: 625–36.

6
[5] Liu, Y., Liang, X. S. and Weisberg, R. H. (2007), Rectification of the bias problem in the
wavelet power spectrum, Journal. Atmos. Ocean. Tech, 24, 2093-2102.

[6] Torrence, C. and Compo, G. (1998). A practical guide to wavelet analysis. Bulletin of the
American Meteorological Society 79: 61–78.

[7] Veleda, D., Montagne, R. and Araujo, M. (2012) Cross-wavelet bias corrected by normal-
izing scales, Journal of Atmospheric and Oceanic Technology 29, 1401–1408.

[8] Zar, J. H. (1996) Biostatistical Analysis (3rd Ed.), Prentice-Hall. Upper Saddle River,
New Jersey.