coh: Coherence
In wsyn: Wavelet Approaches to Studies of Synchrony in Ecology and Other Fields

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.

coh(
  dat1,
  dat2,
  times,
  norm,
  sigmethod = "none",
  nrand = 1000,
  scale.min = 2,
  scale.max.input = NULL,
  sigma = 1.05,
  f0 = 1
)

`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 nth 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 `norm`, see details), and with scalloping of the transforms.
`signif`	A list with information from the significance testing. Elements are `coher` and `scoher`. See details.
`ranks`	A list with ranking information for `signif`. `NA` until `plotrank` is called, see documentation for `plotrank`.
`bandp`	A data frame containing results of computing significances of the coherence across timescale bands. Empty on an initial call to `coh`, filled in by the function `bandtest`. See details.

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")

times<-1:100
dat1<-matrix(rnorm(1000),10,100)
dat2<-matrix(rnorm(1000),10,100)
dat1<-cleandat(dat1,times,1)$cdat
dat2<-cleandat(dat2,times,1)$cdat
norm<-"powall"
sigmethod<-"fast"
nrand<-10
res<-coh(dat1,dat2,times,norm,sigmethod,nrand)
#for real applications, use a much bigger nrand