Type: Package
Title: Vector Wavelet Coherence for Multiple Time Series
Version: 0.1.0
Date: 2021-01-04
Author: Tunc Oygur [aut, cre], Gazanfer Unal [aut], Tarik C. Gouhier [ctb], Aslak Grinsted [ctb], Viliam Simko [ctb]
Maintainer: Tunc Oygur <info@tuncoygur.com.tr>
Description: New wavelet methodology (vector wavelet coherence) (Oygur, T., Unal, G, 2020 <doi:10.1007/s40435-020-00706-y>) to handle dynamic co-movements of multivariate time series via extending multiple and quadruple wavelet coherence methodologies. This package can be used to perform multiple wavelet coherence, quadruple wavelet coherence, and n-dimensional vector wavelet coherence analyses.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://github.com/toygur/vectorwavelet
BugReports: https://github.com/toygur/vectorwavelet/issues
Depends: biwavelet (≥ 0.20.19)
Imports: iterators, spam, maps, fields, foreach, Rcpp
Suggests: knitr, rmarkdown, devtools
Encoding: UTF-8
LazyData: TRUE
RoxygenNote: 7.1.1
NeedsCompilation: no
Packaged: 2021-01-08 19:29:56 UTC; toygur
Repository: CRAN
Date/Publication: 2021-01-13 10:50:02 UTC

Vector wavelet coherence for multiple time series

Description

Description: This package can be used to perform multiple wavelet coherence (mwc), quadruple wavelet coherence (qmwc), and n-dimensional vector wavelet coherence (vwc) analyses.

Author(s)

Tunc Oygur, Gazanfer Unal

Maintainer: Tunc Oygur <info@tuncoygur.com.tr>

Code based on biwavelet package written by Tarik C. Gouhier, Aslak Grinsted, Viliam Simko.

References

T. Oygur, G. Unal.. Vector wavelet coherence for multiple time series. Int. J. Dynam. Control (2020).

T. Oygur, G. Unal.. The large fluctuations of the stock return and financial crises evidence from Turkey: using wavelet coherency and VARMA modeling to forecast stock return. Fluctuation and Noise Letters, 2017

T.C. Gouhier, A. Grinstead and V. Simko. 2016. biwavelet: Conduct univariate and bivariate wavelet analyses (Version 0.20.15). Available from http://github.com/tgouhier/biwavelet

Ng, Eric KW and Chan, Johnny CL. 2012. Geophysical applications of partial wavelet coherence and multiple wavelet coherence. Journal of Atmospheric and Oceanic Technology 29-12:1845–1853.

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

Torrence, C., and G. P. Compo. 1998. A Practical Guide to Wavelet Analysis. Bulletin of the American Meteorological Society 79:61-78.

AR1NV - Estimate the parameters for an AR(1) model

Description

AR1NV - Estimate the parameters for an AR(1) model

Usage

ar1nv(x)

Arguments

x

One dimensional time series vector

Value

Return a list containing:

g

estimate of the lag-one autocorrelation.

a

estimate of the noise variance.

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

Code based on a cross wavelet and wavelet coherence toolbox MATLAB package written by Eric Breitenberger

References

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

Compute multiple wavelet coherence

Description

Compute multiple wavelet coherence

Usage

mwc(
  y,
  x1,
  x2,
  pad = TRUE,
  dj = 1/12,
  s0 = 2 * dt,
  J1 = NULL,
  max.scale = NULL,
  mother = "morlet",
  param = -1,
  lag1 = NULL,
  sig.level = 0.95,
  sig.test = 0,
  nrands = 300,
  quiet = FALSE
)

Arguments

y

time series 1 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x1

time series 2 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x2

time series 3 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

pad

pad the values will with zeros to increase the speed of the transform. Default is TRUE.

dj

spacing between successive scales. Default is 1/12.

s0

smallest scale of the wavelet. Default is 2*dt.

J1

number of scales - 1.

max.scale

maximum scale. Computed automatically if left unspecified.

mother

type of mother wavelet function to use. Can be set to morlet, dog, or paul. Default is morlet. Significance testing is only available for morlet wavelet.

param

nondimensional parameter specific to the wavelet function.

lag1

vector containing the AR(1) coefficient of each time series.

sig.level

significance level. Default is 0.95.

sig.test

type of significance test. If set to 0, use a regular \chi^2 test. If set to 1, then perform a time-average test. If set to 2, then do a scale-average test.

nrands

number of Monte Carlo randomizations. Default is 300.

quiet

Do not display progress bar. Default is FALSE

Value

Return a vectorwavelet object containing:

coi

matrix containg cone of influence

rsq

matrix of wavelet coherence

phase

matrix of phases

period

vector of periods

scale

vector of scales

dt

length of a time step

t

vector of times

xaxis

vector of values used to plot xaxis

s0

smallest scale of the wavelet

dj

spacing between successive scales

mother

mother wavelet used

type

type of vectorwavelet object created (mwc)

signif

matrix containg sig.level percentiles of wavelet coherence based on the Monte Carlo AR(1) time series

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

Code based on MWC MATLAB package written by Eric K. W. Ng and Johnny C. L. Chan.

References

T. Oygur, G. Unal.. Vector wavelet coherence for multiple time series. Int. J. Dynam. Control (2020).

T. Oygur, G. Unal. 2017. The large fluctuations of the stock return and financial crises evidence from Turkey: using wavelet coherency and VARMA modeling to forecast stock return. Fluctuation and Noise Letters

Ng, Eric KW and Chan, Johnny CL. 2012. Geophysical applications of partial wavelet coherence and multiple wavelet coherence. Journal of Atmospheric and Oceanic Technology 29-12:1845–1853.

Examples

old.par <- par(no.readonly=TRUE)

t <- (-100:100)

y <- sin(t*2*pi)+sin(t*2*pi/4)+sin(t*2*pi/8)+sin(t*2*pi/16)+sin(t*2*pi/32)+sin(t*2*pi/64)
x1 <- sin(t*2*pi/8)
x2 <- sin(t*2*pi/32)

y <- cbind(t,y)
x1 <- cbind(t,x1)
x2 <- cbind(t,x2)

## Multiple wavelet coherence
result <- mwc(y, x1, x2, nrands = 10)

result <- mwc(y, x1, x2)


## Plot wavelet coherence and make room to the right for the color bar
## Note: plot function can be used instead of plot.vectorwavelet
par(oma = c(0, 0, 0, 1), mar = c(5, 4, 4, 5) + 0.1,  pin = c(3,3))
plot.vectorwavelet(result, plot.cb = TRUE, main = "Plot multiple wavelet coherence")

par(old.par)

Check the format of multivariate time series

Description

Check the format of multivariate time series

Usage

n.check.data(y, x = NULL)

Arguments

y

time series y in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x

multivariate time series x in matrix format (m rows x (1 + (n-1)) columns). The first column should contain the time steps and the other columns should contain the values.

Value

Returns a named list containing:

t

time steps

dt

size of a time step

n.obs

number of observations

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

Code based on biwavelet package written by Tarik C. Gouhier.

Examples

#Example 1:
t1 <- cbind(1:100, rnorm(100))
n.check.data(y = t1)

#Example 2:
t1 <- cbind(1:100, rnorm(100))
t2 <- cbind(1:100, rnorm(100), rnorm(100), rnorm(100))
n.check.data(y = t1, x = t2)

Helper function

Description

Helper function

Usage

n.check.datum(x)

Arguments

x

matrix

Value

list(t, dt, n.obs)

Note

This function is not exported

Plot vectorwavelet objects

Description

Plot vectorwavelet objects which are multiple wavelet coherence, quadruple wavelet coherence and n-dimensional vector wavelet coherence.

Usage

## S3 method for class 'vectorwavelet'
plot(
  x,
  ncol = 1024,
  fill.cols = NULL,
  xlab = "Time",
  ylab = "Period",
  tol = 1,
  plot.cb = FALSE,
  plot.coi = TRUE,
  lwd.coi = 1,
  col.coi = "white",
  lty.coi = 1,
  alpha.coi = 0.5,
  plot.sig = TRUE,
  lwd.sig = 4,
  col.sig = "black",
  lty.sig = 1,
  bw = FALSE,
  legend.loc = NULL,
  legend.horiz = FALSE,
  arrow.len = min(par()$pin[2]/30, par()$pin[1]/40),
  arrow.lwd = arrow.len * 0.3,
  arrow.cutoff = 0.7,
  arrow.col = "black",
  xlim = NULL,
  ylim = NULL,
  zlim = c(0, 1),
  xaxt = "s",
  yaxt = "s",
  form = "%Y",
  ...
)

Arguments

x

vectorwavelet object generated by mwc, qmec, or vwc.

ncol

number of colors to use. Default is 1024.

fill.cols

Vector of fill colors to be used. Users can specify color vectors using colorRampPalette or brewer.pal from package RColorBrewer. Default is NULL and will generate MATLAB's jet color palette.

xlab

xlabel of the figure. Default is "Time"

ylab

ylabel of the figure. Default is "Period"

tol

tolerance level for significance contours. Sigificance contours will be drawn around all regions of the spectrum where spectrum/percentile >= tol. Default is 1. If strict i^{th} percentile regions are desired, then tol must be set to 1.

plot.cb

plot color bar if TRUE. Default is FALSE.

plot.coi

plot cone of influence (COI) as a semi-transparent polygon if TRUE. Default is TRUE. Areas that fall within the polygon can be affected by edge effects.

lwd.coi

Line width of COI. Default is 1.

col.coi

Color of COI. Default is white.

lty.coi

Line type of COI. Default is 1 for solide lines.

alpha.coi

Transparency of COI. Range is 0 (full transparency) to 1 (no transparency). Default is 0.5.

plot.sig

plot contours for significance if TRUE. Default is TRUE.

lwd.sig

Line width of significance contours. Default is 4.

col.sig

Color of significance contours. Default is black.

lty.sig

Line type of significance contours. Default is 1.

bw

plot in black and white if TRUE. Default is FALSE.

legend.loc

legend location coordinates as defined by image.plot. Default is NULL.

legend.horiz

plot a horizontal legend if TRUE. Default is FALSE.

arrow.len

size of the arrows. Default is based on plotting region (min(par()$pin[2]/30,par()$pin[1]/40).

arrow.lwd

width/thickness of arrows. Default is arrow.len*0.3.

arrow.cutoff

cutoff value for plotting phase arrows. Phase arrows will be be plotted in regions where the significance of the zvalues exceeds arrow.cutoff. If the object being plotted does not have a significance field, regions whose zvalues exceed the arrow.cutoff quantile will be plotted. Default is 0.7.

arrow.col

Color of arrows. Default is black.

xlim

the x limits. The default is NULL.

ylim

the y limits. The default is NULL.

zlim

the z limits. The default is NULL.

xaxt

Add x-axis? The default is s; use n for none.

yaxt

Add y-axis? The default is s; use n for none.

form

format to use to display dates on the x-axis. Default is '%Y' for 4-digit year. See ?Date for other valid formats.

...

other parameters.

Value

No return value, shows the objects plot.

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

Code based on biwavelet package written by Tarik C. Gouhier.

Compute quadruple wavelet coherence

Description

Compute quadruple wavelet coherence

Usage

qmwc(
  y,
  x1,
  x2,
  x3,
  pad = TRUE,
  dj = 1/12,
  s0 = 2 * dt,
  J1 = NULL,
  max.scale = NULL,
  mother = "morlet",
  param = -1,
  lag1 = NULL,
  sig.level = 0.95,
  sig.test = 0,
  nrands = 300,
  quiet = FALSE
)

Arguments

y

time series 1 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x1

time series 2 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x2

time series 3 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x3

time series 4 in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

pad

pad the values will with zeros to increase the speed of the transform. Default is TRUE.

dj

spacing between successive scales. Default is 1/12.

s0

smallest scale of the wavelet. Default is 2*dt.

J1

number of scales - 1.

max.scale

maximum scale. Computed automatically if left unspecified.

mother

type of mother wavelet function to use. Can be set to morlet, dog, or paul. Default is morlet. Significance testing is only available for morlet wavelet.

param

nondimensional parameter specific to the wavelet function.

lag1

vector containing the AR(1) coefficient of each time series.

sig.level

significance level. Default is 0.95.

sig.test

type of significance test. If set to 0, use a regular \chi^2 test. If set to 1, then perform a time-average test. If set to 2, then do a scale-average test.

nrands

number of Monte Carlo randomizations. Default is 300.

quiet

Do not display progress bar. Default is FALSE

Value

Return a vectorwavelet object containing:

coi

matrix containg cone of influence

rsq

matrix of wavelet coherence

phase

matrix of phases

period

vector of periods

scale

vector of scales

dt

length of a time step

t

vector of times

xaxis

vector of values used to plot xaxis

s0

smallest scale of the wavelet

dj

spacing between successive scales

mother

mother wavelet used

type

type of vectorwavelet object created (qmwc)

signif

matrix containg sig.level percentiles of wavelet coherence based on the Monte Carlo AR(1) time series

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

References

T. Oygur, G. Unal.. Vector wavelet coherence for multiple time series. Int. J. Dynam. Control (2020).

T. Oygur, G. Unal. 2017. The large fluctuations of the stock return and financial crises evidence from Turkey: using wavelet coherency and VARMA modeling to forecast stock return. Fluctuation and Noise Letters

Examples

old.par <- par(no.readonly=TRUE)

t <- (-100:100)

y <- sin(t*2*pi)+sin(t*2*pi/4)+sin(t*2*pi/8)+sin(t*2*pi/16)+sin(t*2*pi/32)+sin(t*2*pi/64)
x1 <- sin(t*2*pi/16)
x2 <- sin(t*2*pi/32)
x3 <- sin(t*2*pi/64)

y <- cbind(t,y)
x1 <- cbind(t,x1)
x2 <- cbind(t,x2)
x3 <- cbind(t,x3)

## Quadruple wavelet coherence
result <- qmwc(y, x1, x2, x3, nrands = 10)

result <- qmwc(y, x1, x2, x3)


## Plot wavelet coherence and make room to the right for the color bar
## Note: plot function can be used instead of plot.vectorwavelet
par(oma = c(0, 0, 0, 1), mar = c(5, 4, 4, 5) + 0.1,  pin = c(3,3))
plot.vectorwavelet(result, plot.cb = TRUE, main = "Plot quadruple wavelet coherence")

par(old.par)

Compute n-dimensional vector wavelet coherence

Description

Compute n-dimensional vector wavelet coherence

Usage

vwc(
  y,
  x,
  pad = TRUE,
  dj = 1/12,
  s0 = 2 * dt,
  J1 = NULL,
  max.scale = NULL,
  mother = "morlet",
  param = -1,
  lag1 = NULL,
  sig.level = 0.95,
  sig.test = 0,
  nrands = 300,
  quiet = FALSE
)

Arguments

y

time series y in matrix format (m rows x 2 columns). The first column should contain the time steps and the second column should contain the values.

x

multivariate time series x in matrix format (m rows x n columns). The first column should contain the time steps and the other columns should contain the values.

pad

pad the values will with zeros to increase the speed of the transform. Default is TRUE.

dj

spacing between successive scales. Default is 1/12.

s0

smallest scale of the wavelet. Default is 2*dt.

J1

number of scales - 1.

max.scale

maximum scale. Computed automatically if left unspecified.

mother

type of mother wavelet function to use. Can be set to morlet, dog, or paul. Default is morlet. Significance testing is only available for morlet wavelet.

param

nondimensional parameter specific to the wavelet function.

lag1

vector containing the AR(1) coefficient of each time series.

sig.level

significance level. Default is 0.95.

sig.test

type of significance test. If set to 0, use a regular \chi^2 test. If set to 1, then perform a time-average test. If set to 2, then do a scale-average test.

nrands

number of Monte Carlo randomizations. Default is 300.

quiet

Do not display progress bar. Default is FALSE

Value

Return a vectorwavelet object containing:

coi

matrix containg cone of influence

rsq

matrix of wavelet coherence

phase

matrix of phases

period

vector of periods

scale

vector of scales

dt

length of a time step

t

vector of times

xaxis

vector of values used to plot xaxis

s0

smallest scale of the wavelet

dj

spacing between successive scales

mother

mother wavelet used

type

type of vectorwavelet object created (vwc)

signif

matrix containg sig.level percentiles of wavelet coherence based on the Monte Carlo AR(1) time series

Author(s)

Tunc Oygur (info@tuncoygur.com.tr)

References

T. Oygur, G. Unal.. Vector wavelet coherence for multiple time series. Int. J. Dynam. Control (2020).

Examples

old.par <- par(no.readonly=TRUE)

t <- (-100:100)

y <- sin(t*2*pi)+sin(t*2*pi/4)+sin(t*2*pi/8)+sin(t*2*pi/16)+sin(t*2*pi/32)+sin(t*2*pi/64)
x1 <- sin(t*2*pi/8)
x2 <- sin(t*2*pi/16)
x3 <- sin(t*2*pi/32)
x4 <- sin(t*2*pi/64)

y <- cbind(t,y)
x <- cbind(t,x1,x2,x3,x4)

## n-dimensional multiple wavelet coherence
result <- vwc(y, x, nrands = 10)

result <- vwc(y, x)


## Plot wavelet coherence and make room to the right for the color bar
## Note: plot function can be used instead of plot.vectorwavelet
par(oma = c(0, 0, 0, 1), mar = c(5, 4, 4, 5) + 0.1,  pin = c(3,3))
plot.vectorwavelet(result, plot.cb = TRUE, main = "Plot n-dimensional vwc (n=5)")

par(old.par)