wt.phase.image {WaveletComp}

Image plot of the phases of periodic components for a single time series

Description

This function plots the wavelet phase image for a time series, which is provided by an object of class "analyze.wavelet", or alternatively of class "analyze.coherency". (In the latter case, the series number or name must be specified.) The vertical axis shows the Fourier periods. The horizontal axis shows time step counts, but can be easily transformed into a calendar axis if dates are provided in either row names or as a variable named "date" in the data frame at hand. Both axes can be relabeled. In particular, an option is given to individualize the period and/or time axis by specifying tick marks and labels.

The color levels are defined according to equidistant breakpoints (covering the interval from -pi to +pi), with the number of levels as a further parameter. In addition, there is an option to adopt an individual color palette.

If the default palette is retained, colors indicate the following. Green: Phases close to zero. Red: phases close to +pi. Blue: phases close to -pi.

Further plot design options concern: plot of the cone of influence, plot of contour lines to border areas of significance with respect to cross-wavelet power or wavelet coherency at a given significance level, plot of power ridges.

Finally, there is an option to insert and format a color legend (a right-hand vertical color bar) and to set the plot title. For further processing of the plot, graphical parameters of plot regions are provided as output.

Usage

wt.phase.image(WT, my.series = 1,
       plot.coi = TRUE, 
       plot.contour = TRUE, 
       siglvl = 0.1, col.contour = "white",
       plot.ridge = TRUE, col.ridge = "black", 
       n.levels = 100, 
       color.palette = "rainbow(n.levels, start = 0, end = .7)", 
       useRaster = TRUE, max.contour.segments = 250000,
       plot.legend = TRUE,
       legend.params = list(width = 1.2, shrink = 0.9, mar = 5.1, 
                            n.ticks = 6, 
                            pi.style = TRUE,
                            label.digits = 1, label.format = "f", 
                            lab = NULL, lab.line = 3),
       label.time.axis = TRUE, 
       show.date = FALSE, date.format = NULL, date.tz = NULL, 
       timelab = NULL, timetck = 0.02, timetcl = 0.5,
       spec.time.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),
       main = NULL,
       lwd = 2, lwd.axis = 1, 
       graphics.reset = TRUE,
       verbose = FALSE)

Arguments

WT

an object of class "analyze.wavelet" or "analyze.coherency"

my.series

In case class(WT) = "analyze.coherency": number (1 or 2) or name of the series to be analyzed.

Default: 1.

plot.coi

Plot cone of influence? Logical. Default: TRUE

plot.contour

Plot contour lines to border the area of wavelet power significance? Logical.

Default: TRUE.

siglvl

level of wavelet power significance to be applied to the plot of contour lines.

Default: 0.1.

col.contour

color of contour lines. Default: "white".

plot.ridge

Plot the wavelet power ridge? Logical.

Default: TRUE.

col.ridge

ridge color. Default: "black".

n.levels

Number of color levels. Default: 100.

color.palette

Definition of color levels. (The color palette will be assigned to levels in reverse order!)

Default: "rainbow(n.levels, start = 0, end = .7)".

useRaster

Use a bitmap raster instead of polygons to plot the image? Logical.

Default: TRUE.

max.contour.segments

limit on the number of segments in a single contour line, positive integer.

Default: 250000 (options(...) default settings: 25000).

plot.legend

Plot color legend (a vertical bar of colors and breakpoints)? Logical.

Default: TRUE.

legend.params

a list of parameters for the plot of the color legend; parameter values can be set selectively (style in parts adopted from image.plot in the R package fields by Douglas Nychka):

• [width:] width of legend bar.
  Default: 1.2.

• [shrink:] a vertical shrinkage factor.
  Default: 0.9.

• [mar:] right margin of legend bar.
  Default: 5.1.

• [n.ticks:] number of ticks for labels.
  Default: 6.

• [pi.style:] style of labels, logical: if TRUE, the symbol "pi" is used to label the legend bar; otherwise, labels are numerals.
  Default: TRUE.

• [label.digits:] number of digits of (numerical factors of) labels.
  Default: 1 if pi.style is TRUE, else 2.

• [label.format:] format of labels.
  Default: "f".

• [lab:] axis label.
  Default: NULL.

• [lab.line:] line (in user coordinate units) where to put the axis label.
  Default: 3.

label.time.axis

Label the time axis? Logical.

Default: TRUE.

show.date

Show calendar dates? (Effective only if dates are available as row names or by variable date in the data frame which is analyzed.) Logical.

Default: FALSE.

date.format

the format of calendar date given as a character string, e.g. "%Y-%m-%d", or equivalently "%F"; see strptime for a list of implemented date conversion specifications. Explicit information given here will overturn any specification stored in WT. If unspecified, date formatting is attempted according to as.Date.

Default: NULL.

date.tz

a character string specifying the time zone of calendar date; see strptime. Explicit information given here will overturn any specification stored in WT. If unspecified, "" (the local time zone) is used.

Default: NULL.

timelab

Time axis label.

Default: "index"; in case of a calendar axis: "calendar date".

timetck

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

Default here: 0.02.

timetcl

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

Default here: 0.5.

spec.time.axis

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

• [at:] locations of tick marks (when NULL, default plotting will be applied). Valid tick marks can be provided as numerical values or as dates. Dates are used only in the case show.date = TRUE, however, and date formats should conform to as.Date or the format given in date.format.
  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.

main

an overall title for the plot.

Default: NULL.

lwd

line width of contour lines and ridge.

Default: 2.

lwd.axis

line width of axes (image and legend bar).

Default: 1.

graphics.reset

Reset graphical parameters? Logical.

Default: TRUE.

verbose

Print verbose output on the screen? Logical.

Default: FALSE.

Value

A list of class graphical parameters with the following elements:

op

original graphical parameters

image.plt

image plot region

legend.plt

legend plot region

Author(s)

Angi Roesch and Harald Schmidbauer

References

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

Carmona R., Hwang W.-L., and Torresani B., 1998. Practical Time Frequency Analysis. Gabor and Wavelet Transforms with an Implementation in S. Academic Press, San Diego.

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 Y., Liang X.S., and Weisberg R.H., 2007. Rectification of the Bias in the Wavelet Power Spectrum. Journal of Atmospheric and Oceanic Technology 24, 2093–2102.

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

See Also

analyze.wavelet, wt.image, wt.avg, wt.sel.phases, reconstruct

Examples

 
## Not run: 
## The following example is adopted from Liu et al., 2007:

series.length <- 6*128*24
x1 <- periodic.series(start.period = 1*24, length = series.length)
x2 <- periodic.series(start.period = 8*24, length = series.length)
x3 <- periodic.series(start.period = 32*24, length = series.length)
x4 <- periodic.series(start.period = 128*24, length = series.length)

x <- x1 + x2 + x3 + x4

plot(x, type = "l", xlab = "index", ylab = "", xaxs = "i",
     main = "hourly series with periods of 1, 8, 32, 128 days")

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)  

## Computation of wavelet power:
## 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.wt <- analyze.wavelet(my.data, "x", 
                        loess.span = 0, 
                        dt = 1/24, dj = 1/20, 
                        lowerPeriod = 1/4, 
                        make.pval = TRUE, n.sim = 10)

## Plot of wavelet power spectrum with equidistant color breakpoints:  
wt.image(my.wt, color.key = "i", main = "wavelet power spectrum",
   legend.params = list(lab = "wavelet power levels (equidistant)"),
   periodlab = "period (days)")

## Default image of phases:
wt.phase.image(my.wt, 
   main = "image of phases", 
   periodlab = "period (days)")

## 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
wt.phase.image(my.wt, 
   main = "image of phases", 
   periodlab = "period (days)",
   timelab = "time elapsed (days)",
   spec.time.axis = list(at = index.ticks, labels = index.labels))

## The same plot, but with (automatically produced) calendar axis:
wt.phase.image(my.wt, 
   main = "image of phases", periodlab = "period (days)", 
   show.date = TRUE, date.format = "%F %T")

## For further axis plotting options:
## Please see the examples in our guide booklet,
## URL http://www.hs-stat.com/projects/WaveletComp/WaveletComp_guided_tour.pdf.    

## Image plot of phases with numerals as labels of the color legend bar: 
wt.phase.image(my.wt, 
   legend.params=list(pi.style = FALSE, label.digits = 2))
   

## End(Not run)