clust {wsyn}

Detection and description of clusters of synchronous locations

Description

Generator function for the clust S3 class, which supports tools for detecting clusters (aka, modules, sub-networks, communities, etc.) of especially synchronous locations.

Usage

clust(
  dat,
  times,
  coords,
  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

coords

A data frame containing X,Y coordinates of locations in data, with column names either X and Y or lon and lat or longitude and latitude. The data frame may contain other columns with additional metainformation about the sites.

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.

Clustering is performed using the the eigenvector-based modularity method of Newman (2006).

Value

clust returns an object of class clust. Slots are:

dat

The input

times

The input

coords

The input

methodspecs

A list with elements specifying the method used, and methodological parameters that were in the input.

adj

The adjacency matrix that defines the synchrony network

clusters

A list with one element for each successive split of the networks into subcomponents carried out by the clustering algorithm. Each element is a vector of length equal to the number of nodes in the original network, giving cluster membership of the nodes. The first element is a vector of all 1s, corresponding to before the first clustering split was performed.

modres

A list of the same length as clusters, with each element containing the results of calling modularity on the network split to that level.

mns

Mean time series for modules. A list of the same length as clusters.

wmfs

Wavelet mean fields for modules. NA when clust is first called, but addwmfs causes this entry to be added. It is a list. See documentation for the method addwmfs.

wpmfs

Wavelet phasor mean fields for modules. NA when clust is first called, but addwpmfs causes this entry to be added. It is a list. See documentation for the method addwpmfs.

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

Newman M.E.J. (2006). Finding community structure in networks using the eigenvectors of matrices. Phys Rev E, 74, 036104.

Newman M.E.J. (2006) Modularity and community structure in networks. PNAS 103, 8577-8582.

See Also

cluseigen, modularity, addwmfs, addwpmfs,clust_methods, synmat, plotmap, browseVignettes("wsyn")

Examples

sig<-matrix(.8,5,5)
diag(sig)<-1
lents<-50
if (requireNamespace("mvtnorm",quietly=TRUE))
{
  dat1<-t(mvtnorm::rmvnorm(lents,mean=rep(0,5),sigma=sig))
  dat2<-t(mvtnorm::rmvnorm(lents,mean=rep(0,5),sigma=sig))
}else
{
  dat1<-t(matrix(rep(rnorm(lents),times=5),lents,5))
  dat2<-t(matrix(rep(rnorm(lents),times=5),lents,5))
}
dat<-rbind(dat1,dat2)
times<-1:lents
dat<-cleandat(dat,times,clev=1)$cdat
coords<-data.frame(Y=rep(0,10),X=1:10)
method<-"coh.sig.fast"
res<-clust(dat,times,coords,method,nsurrogs = 50)
#nsurrogs should be much higher for a real application