plot.biwavelet: Plot `biwavelet` objects

Description

Plot biwavelet objects such as the cwt, cross-wavelet and wavelet coherence.

Usage

# S3 method for biwavelet
plot(
  x,
  ncol = 64,
  fill.cols = NULL,
  xlab = "Time",
  ylab = "Period",
  tol = 1,
  plot.cb = FALSE,
  plot.phase = FALSE,
  type = "power.corr.norm",
  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.8,
  arrow.col = "black",
  xlim = NULL,
  ylim = NULL,
  zlim = NULL,
  xaxt = "s",
  yaxt = "s",
  form = "%Y",
  ...
)

Arguments

x: biwavelet object generated by wt, xwt, or wtc.
ncol: Number of colors to use.
fill.cols: Vector of fill colors to be used. Users can specify color vectors using colorRampPalette or brewer.pal from package RColorBrewer. Value NULL generates MATLAB's jet color palette.
xlab: X-label of the figure.
ylab: Y-label of the figure.
tol: Tolerance level for significance contours. Sigificance contours will be drawn around all regions of the spectrum where spectrum/percentile >= tol. If strict \(i^{th}\) percentile regions are desired, then tol must be set to 1.
plot.cb: Plot color bar if TRUE.
plot.phase: Plot phases with black arrows.
type: Type of plot to create. Can be power to plot the power, power.corr to plot the bias-corrected power, power.norm to plot the power normalized by the variance, power.corr.norm to plot the bias-corrected power normalized by the variance, wavelet to plot the wavelet coefficients, or phase to plot the phase.
plot.coi: Plot cone of influence (COI) as a semi-transparent polygon if TRUE. Areas that fall within the polygon can be affected by edge effects.
lwd.coi: Line width of COI.
col.coi: Color of COI.
lty.coi: Line type of COI. Value 1 is for solide lines.
alpha.coi: Transparency of COI. Range is 0 (full transparency) to 1 (no transparency).
plot.sig: Plot contours for significance if TRUE.
lwd.sig: Line width of significance contours.
col.sig: Color of significance contours.
lty.sig: Line type of significance contours.
bw: plot in black and white if TRUE.
legend.loc: Legend location coordinates as defined by image.plot.
legend.horiz: Plot a horizontal legend if TRUE.
arrow.len: Size of the arrows. Default is based on plotting region.
arrow.lwd: Width/thickness of arrows.
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 for wt and xwt objects. For pwtc and wtc objects, phase arrows will be plotted in regions where the rsq value exceeds arrow.cutoff. If the object being plotted does not have a significance field, regions whose z-values exceed the arrow.cutoff quantile will be plotted.
arrow.col: Color of arrows.
xlim: The x limits.
ylim: The y limits.
zlim: The z limits.
xaxt: Add x-axis? Use n for none.
yaxt: Add y-axis? Use n for none.
form: Format to use to display dates on the x-axis. See Date for other valid formats.
...: Other parameters.

Author

Tarik C. Gouhier (tarik.gouhier@gmail.com) Code based on WTC MATLAB package written by Aslak Grinsted.

Details

Arrows pointing to the right mean that x and y are in phase.

Arrows pointing to the left mean that x and y are in anti-phase.

Arrows pointing up mean that x leads y by \(\pi/2\).

Arrows pointing down mean that y leads x by \(\pi/2\).

References

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

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.

Liu, Y., X. San Liang, and R. H. Weisberg. 2007. Rectification of the Bias in the Wavelet Power Spectrum. Journal of Atmospheric and Oceanic Technology 24:2093-2102.

Examples

Run this code

t1 <- cbind(1:100, rnorm(100))
t2 <- cbind(1:100, rnorm(100))

# Continuous wavelet transform
wt.t1 <- wt(t1)

# Plot power
# Make room to the right for the color bar
par(oma = c(0, 0, 0, 1), mar = c(5, 4, 4, 5) + 0.1)
plot(wt.t1, plot.cb = TRUE, plot.phase = FALSE)

# Cross-wavelet transform
xwt.t1t2 <- xwt(t1, t2)

# Plot cross-wavelet
par(oma = c(0, 0, 0, 1), mar = c(5, 4, 4, 5) + 0.1)
plot(xwt.t1t2, plot.cb = TRUE)

# Example of bias-correction
t1 <- sin(seq(0, 2 * 5 * pi, length.out = 1000))
t2 <- sin(seq(0, 2 * 15 * pi, length.out = 1000))
t3 <- sin(seq(0, 2 * 40 * pi, length.out = 1000))

# This aggregate time series should have the same power
# at three distinct periods
s <- t1 + t2 + t3

# Compare plots to see bias-effect on CWT:
# biased power spectrum artificially
# reduces the power of higher-frequency fluctuations.
wt1 <- wt(cbind(1:1000, s))
par(mfrow = c(1,2))
plot(wt1, type = "power.corr.norm", main = "Bias-corrected")
plot(wt1, type = "power.norm", main = "Biased")

# Compare plots to see bias-effect on XWT:
# biased power spectrum artificially
# reduces the power of higher-frequency fluctuations.
x1 <- xwt(cbind(1:1000, s), cbind(1:1000, s))
par(mfrow = c(1,2))

plot(x1, type = "power.corr.norm", main = "Bias-corrected")
plot(x1, type = "power.norm", main = "Biased")

Run the code above in your browser using DataLab