phase.sync: Phase synchrony of quasi-periodic time series
In synchrony: Methods for Computing Spatial, Temporal, and Spatiotemporal Statistics

Description Usage Arguments Details Value Author(s) References Examples

Compute the phase synchrony between two quasi-periodic time series by quantifying their phase difference at each time step

1 2	phase.sync (t1, t2, nrands = 0, mod = 1, method = c("markov", "fft"), nbreaks = 10, mins = FALSE, quiet = FALSE)

`t1`	time series 1 in matrix format (`n` rows x 2 columns). The first column should contain the time steps and the second column should contain the values. If `t1` is a column vector instead of a matrix, then it will be automatically converted to a matrix with column 1 corresponding to a time index ranging from 1 to the length of `t1`.
`t2`	time series 2 in matrix format (`n` rows x 2 columns). The first column should contain the time steps and the second column should contain the values. If `t2` is a column vector instead of a matrix, then it will be automatically converted to matrix with column 1 corresponding to a time index ranging from 1 to the length of `t2`.
`nrands`	number of randomizations to perform (default is 0)
`mod`	flag to indicate whether to compute phase difference modulus 2π between 0 and 2π (`mod=1`) or phase difference modulus 2π between -π and π (`mod=2`). Default is `mod=1`.
`method`	method to generate surrogate time series for Monte Carlo simulations. This can be set to `markov` to use the Markov process described in Cazelles and Stone (2004) or `fft` to use the FFT approach described in Theiler et al. (1992). Default is `method=markov`.
`nbreaks`	number of bins to use to group the values in the time series. Default is `10`.
`quiet`	Suppress progress bar when set to `TRUE`. Default is `FALSE`
`mins`	use local minima instead of local maxima to compute and the interpolate the phase. Default is `FALSE`.

Two time series are phase-locked if the relationship between their phases remains constant over time. This function computes the phase of successive local maxima or minima for each time series and then uses linear interpolation to find the phase at time steps that fall between local maxima/minima. A histogram can be used to determine if the distribution of the phase difference at each time step is uniform (indicating no phase locking) or has a clear peak (indicating phase locking).

Returns a list containing Q.obs, pval, rands, phases1, phases2, deltaphase, and icdf:

`Q.obs`	Phase synchrony ranging from 0 (no phase synchrony) to 1 (full phase synchrony)
`pval`	p-value of observed phase synchrony based on randomization test
`rands`	Monte Carlo randomizations
`phases1`	`n` x 3 matrix containing the timestep, value, and phase of the first time series
`phases2`	`n` x 3 matrix containing the timestep, value, and phase of the second time series
`deltaphase`	`n` x 4 matrix containing the timestep, raw phase difference, phase difference modulus 2π between 0 and 2π, phase difference modulus 2π between -π and π
`icdf`	Inverse cumulative distribution of Q values obtained from Monte Carlo randomizatons

Tarik C. Gouhier (tarik.gouhier@gmail.com)

Cazelles, B., and L. Stone. 2003. Detection of imperfect population synchrony in an uncertain world. Journal of Animal Ecology 72:953–968.

Theiler, J., S. Eubank, A. Longtin, B. Galdrikian, and J. Doyne Farmer. 1992. Testing for nonlinearity in time series: the method of surrogate data. Physica D: Nonlinear Phenomena 58:77–94.

t1=runif(100)
t2=runif(100)
# Compute and interpolate phases using successive local minima
sync.mins=phase.sync(t1, t2, mins=TRUE)
# Compute and interpolate phases using successive local maxima
sync.maxs=phase.sync(t1, t2)
# Plot distribution of phase difference
hist(sync.mins$deltaphase$mod_phase_diff_2pi)