-
Notifications
You must be signed in to change notification settings - Fork 17
/
Copy pathREADME.Rmd
174 lines (140 loc) · 6.84 KB
/
README.Rmd
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
---
output:
md_document:
variant: markdown_github
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r Setup, include=FALSE}
library(biwavelet)
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "inst/doc/webimg/README-"
)
set.seed(0)
```
# biwavelet R package
[](https://travis-ci.org/tgouhier/biwavelet)
[](https://codecov.io/github/tgouhier/biwavelet?branch=master)
[](http://cran.r-project.org/package=biwavelet)
[](http://depsy.org/package/r/biwavelet)
[](http://stackoverflow.com/questions/tagged/biwavelet)
## Download and Install
To download the development version of the package, type the following at the R command line:
```{r Install latest, eval=FALSE}
install.packages("devtools")
devtools::install_github("tgouhier/biwavelet")
```
To download the release version of the package on CRAN, type the following at the R command line:
```{r Instal from CRAN, eval=FALSE}
install.packages("biwavelet")
```
## About biwavelet
The biwavelet R package is a port of the WTC MATLAB program written by Aslak
Grinsted and the wavelet program written by Christopher Torrence and Gibert P.
Compo. This package can be used to perform univariate and bivariate wavelet
analyses. Wavelet analyses are resolved in the time and frequency domains, and
thus ideal for identifying changes over time in the contribution of each
frequency (or period) of a time series.
Since version 0.14, biwavelet also plots the **bias-corrected wavelet** and
**cross-wavelet power spectrum** using the methods described by [Liu et al.
(2007)](#Liu2007) and [Veleda et al. (2012)](#Veleda2012). This correction is
needed because the traditional approach for computing the power spectrum (e.g.,
[Torrence and Compo 1998](#TorrenceCompo1998)) leads to an artificial and
systematic reduction in power at lower periods. To demonstrate this bias, we can
construct a time series by summing three sinusoidal waves each characterized by
the same power at a different period:
```{r ts_3x_sin, fig.width=8, fig.height=4}
t1 <- sin(seq(from = 0, to = 2 * 5 * pi, length = 1000))
t2 <- sin(seq(from = 0, to = 2 * 15 * pi, length = 1000))
t3 <- sin(seq(from = 0, to = 2 * 40 * pi, length = 1000))
timeseries <- t1 + t2 + t3
plot(ts(timeseries), xlab = NA, ylab = NA)
```
The wavelet spectrum of the time series should show peaks of identical power at each of the three
dominant periods. However, the traditional approach leads to a consistent reduction in power at low
periodicities:
```{r wt_bias, fig.width=8, fig.height=4.5}
wt1 <- wt(cbind(1:1000, timeseries))
par(mfrow = c(1,2))
plot(wt1, type = "power.corr.norm", main = "Bias-corrected wavelet power")
plot(wt1, type = "power.norm", main = "Biased wavelet power")
```
This bias also affects the cross-wavelet, which can be used to determine the
time- and frequency-resolved relationship between two time series. The new
version of biwavelet implements the bias-correction developed by [Veleda et al.
(2012)](#Veleda2012). The bias does not affect the wavelet coherence, however.
For instance, MEI and NPGO undergo coherent fluctuations at periodicities of
~64-150 months (5-12 years) between 1966-2010, with peaks in NPGO leading peaks
in MEI by one quarter of a cycle. For help interpreting these results, please
see the references below and the biwavelet manual.
```{r wtc_mei_npgo, include=FALSE, cache=TRUE}
data(enviro.data)
MEI <- subset(enviro.data, select = c("date", "mei"))
NPGO <- subset(enviro.data, select = c("date", "npgo"))
# Compute wavelet coherence of MEI and NPGO using Monte Carlo randomization
wtc.mei.npgo <- wtc(MEI, NPGO)
```
```{r wtc_example, fig.width=8, fig.height=7}
# 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(wtc.mei.npgo, plot.cb = TRUE, plot.phase = TRUE)
```
<!-- Original image:  -->
The biwavelet package can also be used to compute the (dis)similarity between
pairs of time series based on their wavelet spectrum:
## Additional Examples
```{r xwt_example, fig.width=8, fig.height=6}
# Sample time-series
noise1 <- cbind(1:100, rnorm(100))
noise2 <- cbind(1:100, rnorm(100))
# Cross-wavelet
xwt_noise12 <- xwt(noise1, noise2)
# 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(xwt_noise12, plot.cb = TRUE, plot.phase = TRUE,
main = "Cross wavelet power and phase difference (arrows)")
```
## How to cite
The R core development team and the very active community of package authors
have invested a lot of time and effort in creating R as it is today. Please give
credit where credit is due and cite R and R packages when you use them for data
analysis.
```{r Cite me}
citation("biwavelet")
```
## References
<a id="Cazelles2008"/>
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.
<a id="Grinsted2004"/>
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.
<a id="Liu2007"/>
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.
<a id="Rouyer2008"/>
Rouyer, T., J. M. Fromentin, F. Menard, B. Cazelles, K. Briand, R. Pianet, B. Planque, and N. C. Stenseth. 2008.
**Complex interplays among population dynamics, environmental forcing, and exploitation in fisheries**.
Proceedings of the National Academy of Sciences 105:5420–5425.
<a id="TorrenceCompo1998"/>
Torrence, C., and G. P. Compo. 1998.
**A practical guide to wavelet analysis**.
Bulletin of the American Meteorological Society 79:61–78.
<a id="TorrenceWebster1998"/>
Torrence, C., and P. J. Webster. 1998.
**The annual cycle of persistence in the El Niño/Southern Oscillation**.
Quarterly Journal of the Royal Meteorological Society 124:1985–2004.
<a id="Veleda2012"/>
Veleda, D., R. Montagne, and M. Araujo. 2012.
**Cross-Wavelet Bias Corrected by Normalizing Scales**.
Journal of Atmospheric and Oceanic Technology 29:1401-1408.
## Other links
- Biwavelet listed at OpenHub: https://www.openhub.net/p/biwavelet
- Research software impact of Biwavelet (by Depsy): http://depsy.org/package/r/biwavelet