wc.avg: Plot cross-wavelet power averages and wavelet coherence...

Description Usage Arguments Author(s) References See Also Examples

View source: R/wc.avg.R

Description

This function plots cross-wavelet power averages across time, or alternatively wavelet coherence averages, of two time series, which are provided by an object of class "analyze.coherency". The vertical axis shows the Fourier periods. The horizontal axis shows the averages. User-defined minimum and maximum levels can be applied to cross-wavelet power averages, minimum levels can be applied to coherence averages. Also, an option is given to individualize the period axis and/or axis of averages by specifying tick marks and labels.

There is an option to label periods according to significance of averages (if p-values are provided) at given levels of significance. Labels are point symbols along the line of averages which can be assigned individually.

The idea to show significance levels by colors of plotting characters and its implementation has been adopted from Huidong Tian and Bernard Cazelles (archived R package WaveletCo).

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
wc.avg(WC, which.avg = "wp", exponent = 1,
   show.siglvl = TRUE, 
   siglvl = c(0.05, 0.1), 
   sigcol = c("red", "blue"), sigpch = 20, sigcex = 1,
   minimum.level = NULL, maximum.level = NULL,
   label.avg.axis = TRUE, 
   averagelab = NULL, averagetck = 0.02, averagetcl = 0.5,
   spec.avg.axis = list(at = NULL, labels = TRUE, 
                        las = 1, hadj = NA, padj = NA),
   label.period.axis = TRUE, 
   periodlab = NULL, periodtck = 0.02, periodtcl = 0.5,
   spec.period.axis = list(at = NULL, labels = TRUE, 
                           las = 1, hadj = NA, padj = NA),
   show.legend = TRUE, legend.coords = "topright", 
   main = NULL, 
   lwd = 1, col = 1, 
   lwd.axis = 1,
   verbose = FALSE)

Arguments

WC

an object of class "analyze.coherency".

which.avg

Which averages should be plotted?

"wp" : cross-wavelet power
"wc" : wavelet coherence

Default: "wp".

exponent

Exponent applied to averages before plotting; the exponent should be positive.

Default: 1.

show.siglvl

Label periods according to significance of averages? (Effective only if p-values are provided.)

Default: TRUE.

siglvl

a vector of significance levels (of any length and order). Default: c(0.05, 0.1).

sigcol

a vector of colors (should be of same length as and correspond to siglvl, otherwise colors 1 : length(siglvl)).

Default: c("red","blue").

sigpch

a vector of plotting "characters" (symbols) to use as labels of significance. (It should be of same length as and correspond to siglvl to produce different plotting labels, otherwise the default setting is used. A single input value affects all labels.)

Default: 20.

sigcex

a numerical vector working as size of labels of significance. (It should be of same length as and correspond to siglvl to produce different-sized labels, otherwise the default setting is used. A single input value affects all labels. Note that sigcex is affected by cex in par.)

Default: 1.

minimum.level

Minimum plot level of cross-wavelet power or wavelet coherence averages considered.

Default: NULL (referring to minimum level observed).

maximum.level

Maximum plot level of cross-wavelet power averages considered.

Default: NULL (referring to maximum level observed). Wavelet coherence has maximum average level 1 by definition.

label.avg.axis

Label the axis of averages? Logical.

Default: TRUE.

averagelab

Label for the axis of averages.

Default: "average cross-wavelet power" or "average coherence", depending on which.avg.

averagetck

length of tick marks on the axis of averages as a fraction of the smaller of the width or height of the plotting region; see par. If averagetck >= 0.5, averagetck is interpreted as a fraction of the length of the axis of averages, so if averagetck = 1 (and averagetcl = NULL), vertical grid lines will be drawn.
Setting averagetck = NA is to use averagetcl = -0.5 (which is the R default setting of tck and tcl).

Default here: 0.02.

averagetcl

length of tick marks on the axis of averages as a fraction of the height of a line of text; see par. With averagetcl = -0.5 (which is the R default setting of tcl) ticks will be drawn outward.

Default here: 0.5.

spec.avg.axis

a list of tick mark and label specifications for individualized labeling of the axis of averages (only effective if label.avg.axis = TRUE):

  • [at:] locations of tick marks (when NULL, default plotting will be applied). Valid tick marks can be provided as numerical and non-negative values only.
    Default: NULL.

  • [labels:] either a logical value specifying whether annotations at the tick marks are the tick marks themselves, or any vector of labels. If labels is non-logical, at should be of same length.
    Default: TRUE.

  • [las:] the style of axis labels, see par.
    Default: 1 (always horizontal).

  • [hadj:] adjustment of labels horizontal to the reading direction, see axis.
    Default: NA (centering is used).

  • [padj:] adjustment of labels perpendicular to the reading direction (this can be a vector of adjustments for each label), see axis.
    Default: NA (centering is used).

Mismatches will result in a reset to default plotting.

label.period.axis

Label the (Fourier) period axis? Logical.

Default: TRUE.

periodlab

(Fourier) period axis label.

Default: "period".

periodtck

length of tick marks on the period axis as a fraction of the smaller of the width or height of the plotting region; see par. If periodtck >= 0.5, periodtck is interpreted as a fraction of the length of the period axis, so if periodtck = 1 (and periodtcl = NULL), horizontal grid lines will be drawn.
Setting periodtck = NA is to use periodtcl = -0.5 (which is the R default setting of tck and tcl).

Default here: 0.02.

periodtcl

length of tick marks on the period axis as a fraction of the height of a line of text; see par. With periodtcl = -0.5 (which is the R default setting of tcl) ticks will be drawn outward.

Default here: 0.5.

spec.period.axis

a list of tick mark and label specifications for individualized period axis labeling (only effective if label.period.axis = TRUE):

  • [at:] locations of tick marks (when NULL, default plotting will be applied). Valid tick marks can be provided as numerical and positive values only.
    Default: NULL.

  • [labels:] either a logical value specifying whether annotations at the tick marks are the tick marks themselves, or any vector of labels. If labels is non-logical, at should be of same length.
    Default: TRUE.

  • [las:] the style of axis labels, see par.
    Default: 1 (always horizontal).

  • [hadj:] adjustment of labels horizontal to the reading direction, see axis.
    Default: NA (centering is used).

  • [padj:] adjustment of labels perpendicular to the reading direction (this can be a vector of adjustments for each label), see axis.
    Default: NA (centering is used).

Mismatches will result in a reset to default plotting.

show.legend

Include legend of significance levels into the plot? Logical.

Default: TRUE.

legend.coords

coordinates to position the legend (as in function legend).

Default: "topright".

main

an overall title for the plot.

Default: NULL.

lwd

width of line of averages.

Default: 1.

col

color of line of averages.

Default: "black".

lwd.axis

line width of axes.

Default: 1.

verbose

Print verbose output on the screen? Logical.

Default: FALSE.

Author(s)

Angi Roesch and Harald Schmidbauer; credits are also due to Huidong Tian and Bernard Cazelles.

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.

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.

See Also

analyze.coherency, wc.image, wc.sel.phases, wc.phasediff.image, wt.image, wt.avg,
wt.sel.phases, wt.phase.image, reconstruct

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
## Not run: 
## The following example is modified from Veleda et al., 2012:

series.length <- 3*128*24
x1 <- periodic.series(start.period = 1*24, length = series.length)
x2 <- periodic.series(start.period = 2*24, length = series.length)
x3 <- periodic.series(start.period = 4*24, length = series.length)
x4 <- periodic.series(start.period = 8*24, length = series.length)
x5 <- periodic.series(start.period = 16*24, length = series.length)
x6 <- periodic.series(start.period = 32*24, length = series.length)
x7 <- periodic.series(start.period = 64*24, length = series.length)
x8 <- periodic.series(start.period = 128*24, length = series.length)

x <- x1 + x2 + x3 + x4 + 3*x5 + x6 + x7 + x8 + rnorm(series.length)
y <- x1 + x2 + x3 + x4 - 3*x5 + x6 + 3*x7 + x8 + rnorm(series.length)

matplot(data.frame(x, y), type = "l", lty = 1, xaxs = "i", col = 1:2, 
 xlab = "index", ylab = "",
 main = "hourly series with periods of 1, 2, 4, 8, 16, 32, 64, 128 days", 
 sub = "(out of phase at period 16, different amplitudes at period 64)")
legend("topright", legend = c("x","y"), col = 1:2, lty = 1)

## The following dates refer to the local time zone 
## (possibly allowing for daylight saving time):      
my.date <- seq(as.POSIXct("2014-10-14 00:00:00", format = "%F %T"), 
               by = "hour", 
               length.out = series.length)     
my.data <- data.frame(date = my.date, x = x, y = y)

## Computation of cross-wavelet power and wavelet coherence, x over y:
## a natural choice of 'dt' in the 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.
my.wc <- analyze.coherency(my.data, c("x","y"), 
                           loess.span = 0, 
                           dt = 1/24, dj = 1/20, 
                           window.size.t = 1, window.size.s = 1/2, 
                           lowerPeriod = 1/4,
                           make.pval = TRUE, n.sim = 10)

## Plot of cross-wavelet power, 
## with color breakpoints according to quantiles:
wc.image(my.wc, main = "cross-wavelet power spectrum, x over y",
   legend.params = list(lab = "cross-wavelet power levels (quantiles)"),
   periodlab = "period (days)")
## Note:
## The default time axis shows an index of given points in time, 
## which is the count of hours in our example.      
## By default, arrows are plotted which show the phase differences 
## of x over y at respective significant periods. 
## (Please see our guide booklet for further explanation.)
         
## With time elapsed in days 
## (starting from 0 and proceeding in steps of 50 days)
## instead of the (default) time index:
index.ticks  <- seq(1, series.length, by = 50*24)
index.labels <- (index.ticks-1)/24

## Insert your specification of the time axis: 
wc.image(my.wc, color.key = "i", 
   main = "cross-wavelet power spectrum, x over y", 
   legend.params = list(lab = "cross-wavelet power levels (quantiles)"),
   periodlab = "period (days)", timelab = "time elapsed (days)",
   spec.time.axis = list(at = index.ticks, labels = index.labels))
       
## Plot of average cross-wavelet power:
wc.avg(my.wc, siglvl = 0.05, sigcol = "red", periodlab = "period (days)")

## The same plot, but with enhanced symbol size, user-defined axes, 
## minimum and a maximum plot level of averages:
wc.avg(my.wc, siglvl = 0.05, sigcol = "red", sigcex = 1.5, 
   minimum.level = 0, maximum.level = 17, 
   periodlab = "period (days)",
   spec.period.axis = list(at = c(1,2,4,8,16,32,64,128)), 
   spec.avg.axis = list(at = seq(0,16,2)), 
   lwd = 1.5)
       
## Another style of the plot:
## 'cex.axis' in 'par' controls for the size of axis tick labels, 
## while 'cex.lab' controls for the size of axis and legend labels. 
## Note that scaling by 'cex' would also affect 'sigcex'. 
op <- par(no.readonly = TRUE)
par(cex.lab = 1.3, cex.axis = 1.1)
wc.avg(my.wc, siglvl = 0.05, sigcol = "red", sigcex = 1.5, 
   minimum.level = 0, maximum.level = 17, 
   periodlab = "period (days)",
   spec.period.axis = list(at = c(1,2,4,8,16,32,64,128)), 
   spec.avg.axis = list(at = seq(0,16,2)),
   lwd = 1.5)
par(op)      

## Plot of wavelet coherence 
## (with color breakpoints according to quantiles):
wc.image(my.wc, which.image = "wc", main = "wavelet coherence, x over y",
   legend.params = list(label.digits = 3),
   periodlab = "period (days)")
         
## Plot of average wavelet coherence:
wc.avg(my.wc, which.avg = "wc", 
   siglvl = 0.05, sigcol = "red", legend.coords = "topleft", 
   periodlab = "period (days)", 
   lwd = 1.5)

## The same plot, setting the minimum plot level of averages to 0: 
wc.avg(my.wc, which.avg = "wc", 
   siglvl = 0.05, sigcol = "red", legend.coords = "topleft", 
   minimum.level = 0, 
   periodlab = "period (days)", 
   lwd = 1.5)
 
## Please see also the examples in our guide booklet,
## URL http://www.hs-stat.com/projects/WaveletComp/WaveletComp_guided_tour.pdf.


## End(Not run)

WaveletComp documentation built on May 2, 2019, 6:33 a.m.