clust: Detection and description of clusters of synchronous...
In wsyn: Wavelet Approaches to Studies of Synchrony in Ecology and Other Fields

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

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

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
)

`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`.

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

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`.

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

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.

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

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