synmat {wsyn}

Synchrony matrices

Description

Calculate synchrony matrices using a variety of methods

Usage

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
)

Arguments

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.

Details

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.

Value

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

Author(s)

Jonathan Walter, [e-mail]; Daniel Reuman, [e-mail]; Lei Zhao, [e-mail]

References

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

See Also

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

Examples

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)