Description Usage Arguments Details Value Author(s) References See Also Examples

Wavelet coherence and wavelet phase coherence, spatial or for single time series.
Also the generator function for the `coh`

class, which inherits from the `list`

class.

1 2 3 4 5 6 7 8 9 10 11 12 |

`dat1` |
A locations (rows) x time (columns) matrix (for spatial coherence), or a single time series |

`dat2` |
Same format as dat1, same locations and times |

`times` |
The times at which measurements were made, spacing 1 |

`norm` |
The normalization of wavelet transforms to use. Controls the version of the coherence that is performed. One of "none", "phase", "powall", "powind". See details. |

`sigmethod` |
The method for significance testing. One of "none", "fftsurrog1", "fftsurrog2", "fftsurrog12", "aaftsurrog1", "aaftsurrog2", "aaftsurrog12", "fast". See details. |

`nrand` |
Number of surrogate randomizations to use for significance testing. |

`scale.min` |
The smallest scale of fluctuation that will be examined. At least 2. |

`scale.max.input` |
The largest scale of fluctuation guaranteed to be examined |

`sigma` |
The ratio of each time scale examined relative to the next timescale. Should be greater than 1. |

`f0` |
The ratio of the period of fluctuation to the width of the envelope |

If the dimensions of `dat1`

and `dat2`

are *N* by *T*
(*N* is 1 for
vector `dat1`

and `dat2`

), and if the wavelet transform of the *n*th row
of `dati`

is denoted *W_{i,n,σ}(t)*, then the coherence is the
average, over all
locations *n* and times *t* for which wavelet transforms are
available, of the quantity
*w_{1,n,σ}(t)w_{2,n,σ}(t)^{*}*, where the *** represents
complex conjugation and
*w_{i,n,σ}(t)* is a normalization of the wavelet
transform. The normalization used depends
on `norm`

. If `norm`

is "`none`

" then raw wavelet transforms are used.
If `norm`

is "`phase`

" then
*w_{i,n,σ}(t)=W_{i,n,σ}(t)/|W_{i,n,σ}(t)|*,
which gives the wavelet phase coherence, or the spatial wavelet phase coherence if *N>1*.
If `norm`

is "`powall`

" then the normalization is that descibed in the "Wavelet
mean field" section of the Methods of Sheppard et al. (2016), giving the version of the
coherence that was there called simply the wavelet coherence, or the spatial wavelet
coherence if *N>1*. If `norm`

is "`powind`

",
then *w_{i,n,σ}(t)* is obtained
by dividing *W_{i,n,σ}(t)* by the square root of the average of
*W_{i,n,σ}(t)W_{i,n,σ}(t)^{*}* over the times for
which it is defined; this is done
separately for each *i* and *n*.

The slot `signif`

is `NA`

if `sigmethod`

is "`none`

". Otherwise, and
if `sigmethod`

is not "`fast`

", then `signif$coher`

is the same as
`coher`

, and `signif$scoher`

is a matrix of dimensions `nrand`

by
`length(coher)`

with rows with magnitudes equal to coherences of surrogate
datasets, computed using
the normalization specified by `norm`

. The type of surrogate used (Fourier surrogates
or amplitude adjusted Fourier surrogates, see `surrog`

), as well as which of the
datasets surrogates are computed on (`dat1`

, `dat2`

, or both) is determined by
`sigmethod`

. The first part of the value of `sigmethod`

specifies the
type of surrogate used, and the numbers in the second part (1, 2, or 12) specify
whether surrogates are applied to `dat1`

, `dat2`

, or both, respectively.
Synchrony-preserving surrogates are used. A variety of
statements of significance (or lack thereof) can be made
by comparing `signif$coher`

with `signif$scoher`

(see the `plotmag`

,
`plotrank`

, and `bandtest`

methods
for the `coh`

class). If `sigmethod`

is
"`fast`

", the fast algorithm of Sheppard et al. (2017) is used. In that case
`signif$coher`

can be compared to `signif$scoher`

to make significance
statements about the coherence in exactly the same way, but `signif$coher`

will no
longer precisely equal `coher`

, and `coher`

should not be compared
directly to `signif$scoher`

. Statements about significance of the coherence
should be made using `signif$coher`

and `signif$scoher`

, whereas `coher`

should be used whenever the actual value of the coherence is needed. No fast algorithm
exists for `norm`

equal to "`phase`

" (the phase coherence; Sheppard et al, 2017),
so if `norm`

is "`phase`

" and `sigmethod`

is "`fast`

", the function
throws an error.

The slots `ranks`

and `bandp`

are empty on an initial call to `coh`

.
They are made to compute and hold
aggregate significance results over any timescale band of choice. These are filled in
when needed by other methods, see `plotrank`

and `bandtest`

.

Regardless of what the variables represent, the normalized transform of dat1 is multiplied by the conjugate of the normalized transform of dat2. Thus, a positive phase of the coherence indicates dat1 would be leading dat2.

`coh`

returns an object of class `coh`

. Slots are:

`dat1, dat2` |
The input data |

`times` |
The times associated with the data |

`sigmethod` |
The method for significance testing, as inputted. |

`norm` |
The normalization of the wavelet transforms that will be used in computing the coherence. Different values result in different versions of the coherence. One of "none", "phase", "powall", "powind". See details. |

`wtopt` |
The inputted wavelet transform options scale.min, scale.max.input, sigma, f0 in a list |

`timescales` |
The timescales associated with the coherence |

`coher` |
The complex magnitude of this quantity is the coherence, calculated in the usual way (which depends
on |

`signif` |
A list with information from the significance testing. Elements are |

`ranks` |
A list with ranking information for |

`bandp` |
A data frame containing results of computing significances of the coherence across timescale bands.
Empty on an initial call to |

Thomas Anderson, anderstl@gmail.com, Jon Walter, jaw3es@virginia.edu; Lawrence Sheppard, lwsheppard@ku.edu; Daniel Reuman, reuman@ku.edu

Sheppard, L.W., et al. (2016) Changes in large-scale climate alter spatial synchrony of aphid pests. Nature Climate Change. DOI: 10.1038/nclimate2881

Sheppard, L.W., et al. (2017) Rapid surrogate testing of wavelet coherences. European Physical Journal, Nonlinear and Biomedical Physics, 5, 1. DOI: 10.1051/epjnbp/2017000

`cleandat`

, `coh_methods`

, `bandtest`

, `plotmag`

,
`plotphase`

, `plotrank`

, `browseVignettes("wsyn")`

1 2 3 4 5 6 7 8 9 10 |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.