Version: 0.1.0
Title: Surrogate Synchrony
Suggests: gtools
Description: Computes synchrony as windowed cross-correlation based on two-dimensional time series in a text file you can upload. 'SUSY' works as described in Tschacher & Meier (2020) <doi:10.1080/10503307.2019.1612114>.
License: GPL-2
URL: https://wtschacher.github.io/SUSY/
BugReports: https://github.com/wtschacher/SUSY/issues
NeedsCompilation: no
Packaged: 2022-11-22 09:10:45 UTC; jan
Author: Wolfgang Tschacher [aut, cre], David Tschacher [ctb], Jan Gorecki [ctb]
Maintainer: Wolfgang Tschacher <wolfgang.tschacher@upd.unibe.ch>
Repository: CRAN
Date/Publication: 2022-11-24 09:00:13 UTC

susy to data.frame conversion method

Description

Turns susy class object into a data.frame.

Usage

  ## S3 method for class 'susy'
as.data.frame(x, row.names=NULL, optional=FALSE, corr.no.abs=TRUE, ...)

Arguments

x

A susy object.

row.names

Ignored, only for consistency to generic as.data.frame method.

optional

Ignored, only for consistency to generic as.data.frame method.

corr.no.abs

Logical, defaults to TRUE display correlation without the absolute value.

...

Ignored.

Value

Returns data.frame.

See Also

susy

Examples

n = 1000
data = data.frame(
  var1 = runif(n, 300, 330),
  var2 = runif(n, 300, 330)
)
res = susy(data, segment=30L, Hz=15L)
as.data.frame(res)

Surrogate Synchrony - legacy

Description

An internal function, a legacy implementation to compute Surrogate Synchrony, please use susy function instead.
Cross-correlations are computed up to a specific lag in seconds Maxlag, then aggregated within a chosen Segment of e.g. 30s. Aggregation is performed by transforming correlations to Fisher's Z, then computing mean Z in each segment, then across all segments of the time series. Segment shuffling is used to create surrogate time series, on which the same computations are run. This provides effect sizes ES. File: The pairs of time series are in the columns of the file, variable names are in the header line. If Automatic is clicked, the synchrony is computed of all adjacent pairs of columns in the file. If Automatic is unclicked, you may choose the two columns to be analyzed for synchrony, and two plots are additionally prepared. SUSY provides two different synchrony measures of each twin time series: mean Z and ES of mean Z; mean absolute_Z and ES of mean absolute_Z.

Usage

old.susy(
  filename="MEA-topstage-C3-Beethoven.txt", separator=" ", missings=".", datahead=TRUE,
  spalte1=2, spalte2=5, epoche=30, fps=15, maxlag=3, automatic=FALSE,
  plotid=3, plotid2=5, pseudosVereinfachen=FALSE, anzahlPseudosGesamt=500,
  zufallsdaten=FALSE, anzahlzufallsdaten=10000, korrOhneBetragAnzeigen=TRUE,
  permutation=FALSE
)

Arguments

filename

Character scalar, name of a source file. Defaults to "MEA-topstage-C3-Beethoven.txt".

separator

Character scalar, source file data separator. Defaults to " ".

missings

Character scalar, source file data missings marker. Defalts to ".".

datahead

Logical scalar, tells if source data has a header row. Defaults to TRUE.

spalte1

Numeric, first column number of data to use. Defaults to 2.

spalte2

Numeric, second column number of data to use. Defaults to 5.

epoche

Epochengroesse (SEGMENT SIZE) in s (Epoche darf nicht kleiner sein als Zeitfenster/fps). Epoche*fps darf nicht groesser sein als die Anzahl Daten (timepoints) geteilt durch 2. Beispiel 1: timepoints: 1000, fps = 10, also darf Epoche nicht groesser sein als 50s (=1000/(10*2)). Beispiel 2: maxlag : 90, fps = 10, also darf Epoche nicht KLEINER sein als 9s (=90/10).

fps

Numeric, frames per second, sampling rate.

maxlag

Numeric, window size for CCF, maximum lag in seconds, only whole number.

automatic

Logical, if TRUE then all pairs of columns are computed, therefore number of columns must be even and also a plot is not generated.

plotid

Numeric, specifies the type of the first plot, defaults to 3. 1: GMcrosscorrs, 2: synchrony by epoch, 3: GM-Z, 4: time series plot, 5: z not abs.

plotid2

Numeric, specifies the type of the first plot, defaults to 5.

pseudosVereinfachen

Logical, default FALSE. Simplify calculation of the pseudo data.

anzahlPseudosGesamt

Numeric, default 500. Ignored when pseudosVereinfachen is FALSE (default)

zufallsdaten

Logical, if TRUE then use random data, normally distributed numbers in the range [0,50].

anzahlzufallsdaten

Numeric, number of rows in random data.

korrOhneBetragAnzeigen

Logical, defaults to TRUE display correlation without the amount.

permutation

Logical, if TRUE then function computes all pairs combinations between columns provided in x (n*(n-1)/2 pairs)

Value

Returns NULL invisibly. A side effects include:

Note

Function does not handle missing values.

See Also

susy

susy plot method

Description

Generate plot(s) for a susy object.

Usage

  ## S3 method for class 'susy'
plot(x, type=c(4, 5), ...)

Arguments

x

A susy object.

type

Numeric, specifies the types of plot, defaults to c(4, 5).

  1. GMcrosscorrs

  2. synchrony by segments

  3. GM-Z

  4. time series plot

  5. Z not abs

...

Ignored.

Details

Method can generate multiple types of plots by providing numeric vector to type argument. Note it will generate plots for each pair (cross computation) in x, so the final number of plots is length(x) * length(type).

Value

Returns NULL invisibly. Generate plot(s) as a side effect.

See Also

susy

Examples

n = 1000
data = data.frame(
  var1 = runif(n, 300, 330),
  var2 = runif(n, 300, 330),
  var3 = runif(n, 300, 330)
)
res = susy(data, segment=30L, Hz=15L, permutation=TRUE)
plot(res, type=c(3,5))

susy print method

Description

Prints information about an susy object.

Usage

  ## S3 method for class 'susy'
print(x, corr.no.abs=TRUE, legacy=FALSE, ...)

Arguments

x

A susy object.

corr.no.abs

Logical, defaults to TRUE display correlation without the absolute value.

legacy

Logical, defaults to FALSE, when TRUE print will produce an output that matches the output of legacy SUSY implementation.

...

Extra arguments passed to print.data.frame method.

Value

Returns x invisibly. Display output to console as a side effect.

See Also

susy

Examples

n = 1000
data = data.frame(
  var1 = runif(n, 300, 330),
  var2 = runif(n, 300, 330)
)
res = susy(data, segment=30L, Hz=15L)
res
print(res, corr.no.abs=FALSE)
print(res, digits=4)
print(res, legacy=TRUE)

Surrogate Synchrony

Description

Cross-correlations of two time series are computed up to a specific lag in seconds maxlag. Cross-correlation is done within segment of the time series. The size of segments segment can be chosen in seconds. Aggregation is then performed by transforming correlations to Fisher's Z, computing mean Z in each segment, then across all segments of the time series. Segment shuffling is used to create surrogate time series, on which the same computations are run. This provides effect sizes ES. SUSY provides these different synchrony measures for each twin time series: mean Z and ES of mean Z; mean absolute_Z and ES of mean absolute_Z.

Usage

susy(x, segment, Hz, maxlag=3L, permutation=FALSE,
  restrict.surrogates=FALSE, surrogates.total=500)

Arguments

x

A data.frame of numeric columns.

segment

Integer, size in seconds. Must not be smaller than 2 * maxlag, must not be larger than half the the time series (nrow(x)/2).

Hz

Integer, frames per second (sampling rate).

maxlag

Integer, maximum lag for ccf in seconds. Default 3 seconds.

permutation

Logical, default FALSE requires x to have even number of columns which are processed in pairs (1-2, 3-4, etc.). When permutation is TRUE then function computes all pairs combinations between columns provided in x (n*(n-1)/2 pairs).

restrict.surrogates

Logical, default FALSE. Restrict the number of surrogates or not.

surrogates.total

Numeric, the number of generated surrogates, default 500. Ignored when restrict.surrogates is FALSE (default).

Details

Segments are non-overlapping, and the number of segments that fit into the time series may have a remainder (usually a few seconds at the end of the time series), which is not considered.

Value

Object of class susy is returned. Each cross correlation pair is an element in resulting object.

See Also

plot.susy, as.data.frame.susy, print.susy

Examples

n = 1000
data = data.frame(
  var1 = runif(n, 300, 330),
  var2 = runif(n, 300, 330),
  var3 = runif(n, 300, 330)
)

## use only first two columns
res = susy(data[, 1:2], segment=30L, Hz=15L)
length(res)
names(res)

## use all columns and permutation
res = susy(data, segment=30L, Hz=15L, permutation=TRUE)
length(res)
names(res)

## print susy
res
print(res, legacy=TRUE)

## plot susy
plot(res)
plot(res, type=1:2)