synmat: Synchrony matrices
In wsyn: Wavelet Approaches to Studies of Synchrony in Ecology and Other Fields

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

Calculate synchrony matrices using a variety of methods

synmat(
  dat,
  times,
  method,
  tsrange = c(0, Inf),
  nsurrogs = 1000,
  scale.min = 2,
  scale.max.input = NULL,
  sigma = 1.05,
  f0 = 1,
  weighted = TRUE,
  sigthresh = 0.95
)

`dat`	A locations (rows) x time (columns) matrix of measurements
`times`	The times at which measurements were made, spacing 1
`method`	Method for synchrony calculation. See details.
`tsrange`	A vector containing the min and max of the focal timescale range. Defaults to all timescales that are valid given choices for scale.min, scale.max.input, f0, sigma. Only used for wavelet-based methods.
`nsurrogs`	Number of surrogates for significance test. Defaults to 1000. Only used for surrogate-based methods.
`scale.min`	The smallest scale of fluctuation that will be examined. At least 2. Used only for wavelet-based methods.
`scale.max.input`	The largest scale of fluctuation guaranteed to be examined. Only used for wavelet-based methods.
`sigma`	The ratio of each time scale examined relative to the next timescale. Should be greater than 1. Only used for wavelet-based methods.
`f0`	The ratio of the period of fluctuation to the width of the envelope. Only used for wavelet-based methods.
`weighted`	If `TRUE`, create a weighted network. If `FALSE`, create a binary network using statistical significance. Binary networks are only allowed for networks based on significance.
`sigthresh`	Significance threshold needed, if `weighted` is false, for a network link to be realized. Typically 0.95, 0.99, or 0.999, etc. Only used if `weighted` is `FALSE`.

The following values are valid for method: "pearson", "pearson.sig.std", "pearson.sig.fft", "pearson.sig.aaft", "spearman", "spearman.sig.std", "spearman.sig.fft", "spearman.sig.aaft", "kendall", "kendall.sig.std", "kendall.sig.fft", "kendall.sig.aaft", "ReXWT", "ReXWT.sig.fft", "ReXWT.sig.aaft", "ReXWT.sig.fast", "coh", "coh.sig.fft", "coh.sig.aaft", "coh.sig.fast", "phasecoh", "phasecoh.sig.fft", and "phasecoh.sig.aaft". The first portions of these identifiers correspond to the Pearson, Spearman, and Kendall correlations, the real part of the cross-wavelet transform, the wavelet coherence, and the wavelet phase coherence. The second portions of these identifiers, when present, indicates that significance of the measure specified in the first portion of the identifies is to be used for establishing the synchrony matrix. Otherwise the value itself is used. The third part of the method identifier indicates what type of significance is used.

Significance testing is performed using standard approaches (method flag containg std; for correlation coefficients, although these are inappropriate for autocorrelated data), or surrogates generated using the Fourier (method flag containing "fft") or amplitude adjusted Fourier surrogates ("aaft"). For "coh" and "ReXWT", the fast testing algorithm of Sheppard et al. (2017) is also implemented ("fast"). That method uses implicit Fourier surrogates. The choice of wavelet coherence (method flag containing "coh") or the real part of the cross-wavelet transform (method flag containing "ReXWT") depends mainly on treatment of out-of-phase relationships. The "ReXWT" is more akin to a correlation coefficient in that strong in-phase relationships approach 1 and strong antiphase relationships approach -1. Wavelet coherence allows any phase relationship and ranges from 0 to 1. Power normalization is applied for "coh" and for "ReXWT". All significance tests are one-tailed. Synchrony matrices for significance-based methods when weighted is TRUE contain 1 minus the p-values.

synmat returns a synchrony matrix, of type depending on the method argument. See details. Diagonal entries are left as NA.

Jonathan Walter, jaw3es@virginia.edu; Daniel Reuman, reuman@ku.edu; Lei Zhao, lei.zhao@cau.edu.cn

Walter, J. A., et al. (2017) The geography of spatial synchrony. Ecology Letters. doi: 10.1111/ele.12782

clust, coh, surrog, browseVignettes("wsyn")

sig<-matrix(.9,5,5)
diag(sig)<-1
if (requireNamespace("mvtnorm",quietly=TRUE))
{
  dat1<-t(mvtnorm::rmvnorm(30,mean=rep(0,5),sigma=sig))
  dat2<-t(mvtnorm::rmvnorm(30,mean=rep(0,5),sigma=sig))
}else
{
  dat1<-t(matrix(rep(rnorm(30),times=5),30,5))
  dat2<-t(matrix(rep(rnorm(30),times=5),30,5))
}
dat<-rbind(dat1,dat2)
times<-1:30
dat<-cleandat(dat,times,clev=2)$cdat
method<-"pearson.sig.fft"
res<-synmat(dat,times,method,nsurrogs=100,weighted=FALSE,
            sigthresh=0.95)