# WaveletCoherency: Computation of the cross-wavelet power and wavelet coherence... In WaveletComp: Computational Wavelet Analysis

## Description

Given two time series x and y having the same length and timestamp, this function computes the cross-wavelet power and wavelet coherence applying the Morlet wavelet, subject to criteria concerning: the time and frequency resolution, an (optional) lower and/or upper Fourier period, and filtering method for the coherence computation.

The output is further processed by the higher-order function `wc` and can be retrieved from `analyze.coherency`.

The name and layout were inspired by a similar function developed by Huidong Tian and Bernard Cazelles (archived R package `WaveletCo`). The implementation of a choice of filtering windows for the computation of the wavelet coherence was inspired by Luis Aguiar-Conraria and Maria Joana Soares (`GWPackage`).

## Usage

 ```1 2 3 4``` ```WaveletCoherency(x, y, dt = 1, dj = 1/20, lowerPeriod = 2*dt, upperPeriod = floor(length(x)*dt/3), window.type.t = 1, window.type.s = 1, window.size.t = 5, window.size.s = 1/4) ```

## Arguments

 `x` the time series x to be analyzed `y` the time series y to be analyzed (of the same length as x
 `dt` time resolution, i.e. sampling resolution in the time domain, `1/dt` = number of observations per time unit. For example: a natural choice of `dt` in case of hourly data is `dt = 1/24`, resulting in one time unit equaling one day. This is also the time unit in which periods are measured. If `dt = 1`, the time interval between two consecutive observations will equal one time unit. Default: `1`. `dj` frequency resolution, i.e. sampling resolution in the frequency domain, `1/dj` = number of suboctaves (voices per octave). Default: `1/20`.
 `lowerPeriod` lower Fourier period (measured in time units determined by `dt`, see the explanations concerning `dt`) for wavelet decomposition. If `dt = 1`, the minimum admissible value is 2. Default: `2*dt`. `upperPeriod` upper Fourier period (measured in time units determined by `dt`, see the explanations concerning `dt`) for wavelet decomposition. Default: `(floor of one third of time series length)*dt`.
`window.type.t`

type of window for smoothing in time direction; select from:

 `0` (`"none"`) : no smoothing in time direction `1` (`"bar"`) : Bartlett `2` (`"tri"`) : Triangular (Non-Bartlett) `3` (`"box"`) : Boxcar (Rectangular, Dirichlet) `4` (`"han"`) : Hanning `5` (`"ham"`) : Hamming `6` (`"bla"`) : Blackman

Default: `1` = `"bar"`.

`window.type.s`

type of window for smoothing in scale (period) direction; select from:

 `0` (`"none"`) : no smoothing in scale (period) direction `1` (`"bar"`) : Bartlett `2` (`"tri"`) : Triangular (Non-Bartlett) `3` (`"box"`) : Boxcar (Rectangular, Dirichlet) `4` (`"han"`) : Hanning `5` (`"ham"`) : Hamming `6` (`"bla"`) : Blackman

Default: `1` = `"bar"`.

`window.size.t`

size of the window used for smoothing in time direction, measured in time units determined by `dt`, see the explanations concerning `dt`. Default: `5`, which together with `dt = 1` defines a window of length `5*(1/dt)` = 5, equaling 5 observations (observation epochs). Windows of even-numbered sizes are extended by 1.

`window.size.s`

size of the window used for smoothing in scale (period) direction in units of `1/dj`. Default: `1/4`, which together with `dj = 1/20` defines a window of length `(1/4)*(1/dj)` = 5. Windows of even-numbered sizes are extended by 1.

## Value

A list with the following elements:

 `Wave.xy` (complex-valued) cross-wavelet transform (analogous to Fourier cross-frequency spectrum, and to the covariance in statistics) `sWave.xy` smoothed (complex-valued) cross-wavelet transform `Power.xy` cross-wavelet power (analogous to Fourier cross-frequency power spectrum) `Coherency` (complex-valued) wavelet coherency of series x over series y in the time/frequency domain, affected by smoothing (analogous to Fourier coherency, and to the coefficient of correlation in statistics) `Coherence` wavelet coherence (analogous to Fourier coherence, and to the coefficient of determination in statistics (affected by smoothing) `Wave.x, Wave.y` (complex-valued) wavelet transforms of series x and y `Phase.x, Phase.y` phases of series x and y `Ampl.x, Ampl.y` amplitudes of series x and y `Power.x, Power.y` wavelet power of series x and y `sPower.x, sPower.y` smoothed wavelet power of series x and y
 `Period` the Fourier periods (measured in time units determined by `dt`, see the explanations concerning `dt`) `Scale` the scales (the Fourier periods divided by the Fourier factor)
 `nc` number of columns = number of observations = number of observation epochs; "epoch" meaning point in time `nr` number of rows = number of scales (Fourier periods)

## Author(s)

Angi Roesch and Harald Schmidbauer; credits are also due to Huidong Tian, Bernard Cazelles, Luis Aguiar-Conraria, and Maria Joana Soares.

## References

Aguiar-Conraria L., and Soares M.J., 2011. Business cycle synchronization and the Euro: A wavelet analysis. Journal of Macroeconomics 33 (3), 477–489.

Aguiar-Conraria L., and Soares M.J., 2011. The Continuous Wavelet Transform: A Primer. NIPE Working Paper Series 16/2011.

Aguiar-Conraria L., and Soares M.J., 2012. `GWPackage`. Available at https://sites.google.com/site/aguiarconraria/joanasoares-wavelets; accessed September 4, 2013.

Cazelles B., Chavez M., Berteaux, D., Menard F., Vik J.O., Jenouvrier S., and Stenseth N.C., 2008. Wavelet analysis of ecological time series. Oecologia 156, 287–304.

Liu P.C., 1994. Wavelet spectrum analysis and ocean wind waves. In: Foufoula-Georgiou E., and Kumar P., (eds.), Wavelets in Geophysics, Academic Press, San Diego, 151–166.

Tian, H., and Cazelles, B., 2012. `WaveletCo`. Available at https://cran.r-project.org/src/contrib/Archive/WaveletCo/, archived April 2013; accessed July 26, 2013.

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

Veleda D., Montagne R., and Araujo M., 2012. Cross-Wavelet Bias Corrected by Normalizing Scales. Journal of Atmospheric and Oceanic Technology 29, 1401–1408.

`WaveletTransform`, `wc`, `analyze.coherency`