Package 'PhysioAnalysis'

Description

Computes the Augmented Dickey-Fuller test statistic for a unit root (non-stationarity) in a one-dimensional signal. The test regresses the first difference on a constant, the lagged level, and lag lagged first differences, $\Delta y_t = \alpha + \beta y_{t-1} + \sum_{i=1}^{L} \gamma_i \Delta y_{t-i} + \varepsilon_t$, and returns the t-statistic on $\beta$. A large negative statistic (below the Dickey-Fuller critical value) rejects the unit-root null in favour of stationarity. The statistic is the same deterministic OLS quantity as statsmodels.tsa.stattools.adfuller(..., autolag = None).

Usage

adfTest(x, lag = 1L)

Arguments

Details

Note: only the statistic is computed here (it is an exact regression quantity). The critical values and p-value require the Dickey-Fuller / MacKinnon reference tables (an approximation), so they are not returned; compare the statistic against the tabulated critical value for the decision.

Value

A list with statistic (the ADF t-statistic on the lagged level), n (the regression sample size), and lag.

References

Dickey, D.A., Fuller, W.A. (1979). Distribution of the estimators for autoregressive time series with a unit root. JASA, 74, 427-431.

See Also

autocorrelation, ljungBoxTest

Examples

set.seed(1)
adfTest(cumsum(rnorm(500)), lag = 1)$statistic   # random walk -> not far below 0

Description

Converts a connectivity matrix into an adjacency matrix for network analysis.

Usage

adjacencyMatrix(connectivity, threshold = NULL, absolute = FALSE)

Arguments

Value

A square adjacency matrix.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(500 * 4), nrow = 500, ncol = 4)),
  samplingRate = 100
)
conn <- correlationMatrix(pe)
adj <- adjacencyMatrix(conn, threshold = 0.3)

Description

Performs one-way ANOVA at each time point and channel across multiple conditions.

Usage

anovaEpochs(x, groups)

Arguments

Value

A list containing:

References

Maris, E. & Oostenveld, R. (2007). "Nonparametric statistical testing of EEG- and MEG-data." Journal of Neuroscience Methods, 164(1), 177-190. doi:10.1016/j.jneumeth.2007.03.024

See Also

tTestEpochs() for pairwise comparisons, clusterPermutationTest() for multiple comparison correction, effectSize() for Cohen's d effect size.

Examples

# Create example epoched data with conditions
set.seed(123)
epochs <- array(rnorm(100 * 4 * 30 * 1), dim = c(100, 4, 30, 1))
pe <- PhysioExperiment(
  assays = list(epoched = epochs),
  samplingRate = 100,
  metadata = list(
    epoch_info = S4Vectors::DataFrame(
      condition = rep(c("A", "B", "C"), each = 10)
    )
  )
)
# ANOVA across conditions
result <- anovaEpochs(pe, groups = "condition")

Description

Computes the parametric AR spectral density of a one-dimensional signal from an autoregressive model of order order fitted by Yule-Walker (via arYuleWalker): $S(f) = \sigma^2 / |1 - \sum_k \phi_k e^{-i 2\pi f k}|^2$, evaluated on n_freq normalized frequencies in $[0, 0.5]$. Unlike the periodogram / Welch estimate, the AR spectrum is smooth and low-variance, with sharp peaks at resonant frequencies, using only order parameters. It matches stats::spec.ar (including its small-sample innovation-variance convention $N/(N-p-1)$).

Usage

arSpectrum(x, order = 8L, n_freq = 500L)

Arguments

Value

A list with freq (normalized frequencies, cycles/sample), spec (the AR spectral density), and order.

References

Percival, D.B., Walden, A.T. (1993). Spectral Analysis for Physical Applications. Cambridge University Press.

See Also

arYuleWalker, spec.ar

Examples

set.seed(1)
s <- arSpectrum(as.numeric(arima.sim(list(ar = c(0.6, -0.3)), 500)), order = 2)
s$freq[which.max(s$spec)]   # peak (normalized) frequency

Description

Fits an autoregressive model of order order to a one-dimensional signal by the Yule-Walker method: the AR coefficients solve the Yule-Walker equations formed from the signal's biased demeaned autocovariance (obtained via the Durbin-Levinson recursion on autocorrelation), and the innovation variance is the residual (one-step prediction) variance. This is the same definition as statsmodels.regression.linear_model.yule_walker(method = "mle"). AR modelling underlies forecasting, parametric (AR) spectra, and – with the order chosen from the partialAutocorrelation cut-off – compact descriptions of oscillatory dynamics.

Usage

arYuleWalker(x, order = 4L)

Arguments

Value

A list with ar (the length-order AR coefficient vector $\phi_1, \dots, \phi_p$), var_pred (the innovation / one-step prediction variance), and order.

References

Box, G.E.P., Jenkins, G.M. (1976). Time Series Analysis: Forecasting and Control. Holden-Day.

See Also

autocorrelation, partialAutocorrelation, ar.yw

Examples

set.seed(1)
arYuleWalker(as.numeric(arima.sim(list(ar = c(0.5, -0.3)), 500)), order = 2)

Description

Computes the sample autocorrelation function of a one-dimensional signal at lags 0, 1, ..., lag_max using the biased estimator (dividing each autocovariance by $N$), with the mean removed by default – the same definition as stats::acf() and statsmodels.tsa.acf(adjusted = FALSE). The autocorrelation measures how similar a signal is to a time-shifted copy of itself, and is the basic tool for detecting periodicity, rhythmicity, and the decorrelation time of a physiological signal.

Usage

autocorrelation(x, lag_max = 30L, demean = TRUE)

Arguments

Value

A numeric vector of autocorrelation coefficients at lags 0:lag_max; the lag-0 value is always 1.

References

Box, G.E.P., Jenkins, G.M. (1976). Time Series Analysis: Forecasting and Control. Holden-Day.

See Also

acf

Examples

set.seed(1)
autocorrelation(sin(seq(0, 20 * pi, length.out = 500)), lag_max = 20)

Description

Computes the average across epochs, optionally by condition.

Usage

averageEpochs(x, by = NULL)

Arguments

Value

A PhysioExperiment object with an "averaged" assay containing the mean signal across epochs. If by is specified, the third dimension corresponds to conditions.

References

Luck, S.J. (2014). "An Introduction to the Event-Related Potential Technique." 2nd ed. MIT Press.

See Also

epochData() to create epoched data, grandAverage() for averaging across subjects, plotERP() for ERP visualization.

Description

Extracts power in specified frequency bands.

Usage

bandPower(x, bands = NULL, method = c("welch", "wavelet"), relative = FALSE)

Arguments

Value

A data.frame with one row per channel and columns for the channel name and power in each frequency band. If relative = TRUE, values represent the proportion of total power.

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

spectrogram() for full time-frequency decomposition, waveletTransform() for wavelet-based power, fftSignals() for raw FFT, plotPSD() for power spectral density visualization.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(2560), nrow = 256, ncol = 10)),
  colData = S4Vectors::DataFrame(label = paste0("Ch", 1:10)),
  samplingRate = 256
)

# Compute band power for standard EEG bands
bp <- bandPower(pe)
head(bp)

# Compute relative band power
bp_rel <- bandPower(pe, relative = TRUE)

Description

Calculates betweenness centrality for each node.

Usage

betweennessCentrality(
  adjacency,
  normalized = TRUE,
  use_cpp = TRUE,
  n_cores = 1L
)

Arguments

Value

A numeric vector of betweenness centrality values.

Examples

# Star network - center node should have highest betweenness
adj <- matrix(0, 4, 4)
adj[1, 2:4] <- 1
adj[2:4, 1] <- 1
betweennessCentrality(adj)

Description

Converts a weighted adjacency matrix to a binary network.

Usage

binarizeNetwork(adjacency, threshold = 0)

Arguments

Value

A binary adjacency matrix (0s and 1s).

Examples

set.seed(123)
adj <- matrix(c(0, 0.5, 0.3, 0.5, 0, 0.8, 0.3, 0.8, 0), 3, 3)
bin <- binarizeNetwork(adj)

Description

Computes bootstrap confidence intervals for averaged epochs.

Usage

bootstrapCI(
  x,
  n_bootstrap = 1000L,
  ci_level = 0.95,
  condition = NULL,
  seed = NULL
)

Arguments

Value

A list containing:

References

Maris, E. & Oostenveld, R. (2007). "Nonparametric statistical testing of EEG- and MEG-data." Journal of Neuroscience Methods, 164(1), 177-190. doi:10.1016/j.jneumeth.2007.03.024

See Also

effectSize() for Cohen's d effect size, tTestEpochs() for parametric significance testing, plotERP() for ERP visualization.

Examples

# Create example epoched data
set.seed(123)
epochs <- array(rnorm(100 * 4 * 20 * 1), dim = c(100, 4, 20, 1))
pe <- PhysioExperiment(
  assays = list(epoched = epochs),
  samplingRate = 100
)
# Bootstrap CI
result <- bootstrapCI(pe, n_bootstrap = 500)

Description

Cliff's delta, delta = P(X > Y) - P(X < Y), a non-parametric effect size in ⁠[-1, 1]⁠ whose sign follows the direction of the difference. The confidence interval uses Cliff's (1993) consistent variance with his asymmetric in-bounds transform.

Usage

cliffsDelta(x, y, conf_level = 0.95)

Arguments

Value

A list with delta, ci_lower, ci_upper, the variance estimate and the sample sizes.

References

Cliff, N. (1993). Psychol Bull 114(3):494-509.

See Also

rankBiserial(), effectSize()

Examples

cliffsDelta(c(5, 6, 7, 8), c(1, 2, 3, 9))

Description

Calculates the local clustering coefficient for each node.

Usage

clusteringCoefficient(
  adjacency,
  weighted = FALSE,
  use_cpp = TRUE,
  n_cores = 1L
)

Arguments

Value

A numeric vector of clustering coefficients.

Examples

# Fully connected triangle
adj <- matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3, 3)
clusteringCoefficient(adj)  # Should be 1 for all nodes

Description

Performs cluster-based permutation testing for multiple comparison correction. Identifies clusters of significant effects and computes cluster-level p-values.

Usage

clusterPermutationTest(
  x,
  condition1 = NULL,
  condition2 = NULL,
  n_permutations = 1000L,
  cluster_threshold = 0.05,
  tail = 0L,
  seed = NULL,
  n_cores = NULL,
  method = c("cluster", "tfce"),
  tfce_E = 0.5,
  tfce_H = 2,
  tfce_dh = NULL,
  adjacency = NULL
)

Arguments

Value

A list containing:

References

Maris, E. & Oostenveld, R. (2007). "Nonparametric statistical testing of EEG- and MEG-data." Journal of Neuroscience Methods, 164(1), 177-190. doi:10.1016/j.jneumeth.2007.03.024

See Also

tTestEpochs() for pointwise t-tests, correctPValues() for traditional multiple comparison correction, findSignificantWindows() for identifying significant time windows.

Examples

# Create example epoched data
set.seed(123)
epochs <- array(rnorm(50 * 4 * 20 * 1), dim = c(50, 4, 20, 1))
# Add effect to condition 2
epochs[20:30, 1:2, 11:20, 1] <- epochs[20:30, 1:2, 11:20, 1] + 1
pe <- PhysioExperiment(
  assays = list(epoched = epochs),
  samplingRate = 100
)
# Cluster permutation test
result <- clusterPermutationTest(pe, 1:10, 11:20, n_permutations = 100)

# With parallel processing (faster for large datasets)
# result <- clusterPermutationTest(pe, 1:10, 11:20, n_cores = 4)

Description

Functions for computing functional connectivity between channels including coherence, phase synchrony measures, and correlation-based metrics. Compute coherence between channels

Usage

coherence(
  x,
  channels = NULL,
  freq_range = NULL,
  nperseg = 256L,
  noverlap = NULL,
  assay_name = NULL
)

Arguments

Details

Calculates the magnitude-squared coherence between pairs of channels, which measures the linear correlation between signals as a function of frequency.

Coherence is computed using Welch's averaged periodogram method. Values range from 0 (no linear relationship) to 1 (perfect linear relationship).

Value

A list with components:

References

Nolte, G., et al. (2004). "Identifying true brain interaction from EEG data using the imaginary part of coherency." Clinical Neurophysiology, 115(10), 2292-2307. doi:10.1016/j.clinph.2004.04.029

See Also

crossSpectrum() for the underlying cross-spectral density, plv() for phase-based connectivity, connectivityMatrix() for a unified connectivity interface.

Examples

# Create example with 4 channels
set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(4000), nrow = 1000, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 256
)

# Compute coherence
coh <- coherence(pe, freq_range = c(1, 50))
dim(coh$coherence)  # frequencies x channels x channels

Description

High-level function to compute connectivity using various metrics.

Usage

connectivityMatrix(
  x,
  method = c("coherence", "plv", "pli", "wpli", "correlation"),
  freq_band = NULL,
  channels = NULL,
  assay_name = NULL
)

Arguments

Value

A numeric matrix (channel x channel) of connectivity values. For "coherence", returns the mean coherence across frequencies. For phase-based methods ("plv", "pli", "wpli"), returns values between 0 and 1. For "correlation", returns values between -1 and 1.

References

Lachaux, J.-P., et al. (1999). "Measuring phase synchrony in brain signals." Human Brain Mapping, 8(4), 194-208. doi:10.1002/(SICI)1097-0193(1999)8:4<194::AID-HBM4>3.0.CO;2-C

See Also

coherence(), plv(), pli(), wPLI(), correlationMatrix() for individual connectivity methods.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(4000), nrow = 1000, ncol = 4)),
  samplingRate = 256
)

# Compute PLV connectivity in alpha band
conn <- connectivityMatrix(pe, method = "plv", freq_band = c(8, 12))

Description

Applies multiple comparison correction to p-values.

Usage

correctPValues(p_values, method = c("fdr", "bonferroni", "holm", "bh", "none"))

Arguments

Value

Corrected p-values in the same format as input.

References

Maris, E. & Oostenveld, R. (2007). "Nonparametric statistical testing of EEG- and MEG-data." Journal of Neuroscience Methods, 164(1), 177-190. doi:10.1016/j.jneumeth.2007.03.024

See Also

clusterPermutationTest() for cluster-based correction, tTestEpochs() for pointwise t-tests, findSignificantWindows() for identifying significant time windows.

Examples

# Example p-values
p <- matrix(runif(100), nrow = 10)
# Apply FDR correction
p_corrected <- correctPValues(p, method = "fdr")

Description

Calculates the Pearson correlation coefficient between all channel pairs.

Usage

correlationMatrix(
  x,
  channels = NULL,
  method = c("pearson", "spearman", "kendall"),
  assay_name = NULL
)

Arguments

Value

A numeric correlation matrix (channel x channel) with values ranging from -1 to 1. Row and column names are set to channel names when available.

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

coherence() for frequency-domain coherence, plv() for phase-based connectivity, connectivityMatrix() for a unified connectivity interface.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(4000), nrow = 1000, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 256
)

# Compute Pearson correlation
cor_matrix <- correlationMatrix(pe)

Description

Tests the association between two matched numeric vectors. Returns the correlation coefficient, its two-sided p-value (from the exact t-test on the Pearson/Spearman correlation) and the degrees of freedom. For method = "pearson" it reproduces stats::cor.test and scipy.stats.pearsonr bit-for-bit.

Usage

correlationTest(x, y = NULL, method = c("pearson", "spearman"))

Arguments

Value

A list with statistic (the correlation coefficient), p_value (two-sided) and df ($n - 2$).

See Also

pairedTTest, signalMoments.

Examples

set.seed(1); x <- rnorm(50); correlationTest(x, x + rnorm(50))$statistic  # ~0.7

Description

Cronbach's alpha, the standard index of a scale's internal-consistency reliability: how consistently a set of k items measures a single construct. Computed from the item variances and the total-score variance. The raw alpha and the mean inter-item correlation reproduce base R, the psych package (psych::alpha raw_alpha) and pingouin.cronbach_alpha bit-for-bit.

Usage

cronbachAlpha(x)

Arguments

Value

A list with alpha (raw Cronbach's alpha), average_r (mean inter-item correlation), k (items) and n (respondents).

Examples

cronbachAlpha(matrix(round(runif(150, 1, 5)), ncol = 5))

Description

Calculates the cross-spectral density between channel pairs.

Usage

crossSpectrum(
  x,
  channels = NULL,
  nperseg = 256L,
  noverlap = NULL,
  assay_name = NULL
)

Arguments

Value

A list with the following components:

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

coherence() for magnitude-squared coherence, connectivityMatrix() for a unified connectivity interface, spectrogram() for single-channel spectral analysis.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(2000), nrow = 500, ncol = 4)),
  samplingRate = 256
)

# Compute cross-spectral density
csd <- crossSpectrum(pe)

Description

Dunn's test: all pairwise rank-based comparisons following a Kruskal-Wallis test (kruskalTest), using the shared tie-corrected rank variance and a chosen multiple-comparison adjustment. It is the non-parametric counterpart of Tukey's HSD (tukeyHSD). The z-statistics and adjusted p-values reproduce base R's Dunn formula, the PMCMRplus package and scikit_posthocs.posthoc_dunn to machine precision.

Usage

dunnTest(x, ..., p_adjust = c("bonferroni", "none", "holm", "BH"))

Arguments

Value

A data frame with one row per pair: comparison, z, p_value (two-sided, unadjusted) and p_adj, carrying k, n as attributes.

See Also

kruskalTest, tukeyHSD

Examples

dunnTest(list(a = rnorm(20), b = rnorm(20, 1), c = rnorm(20, 2)))

Description

Calculates the standardized mean difference at each time point and channel, with an exact non-central-t confidence interval (Cumming 2014) and an optional Hedges small-sample bias correction.

Usage

effectSize(
  x,
  condition1 = NULL,
  condition2 = NULL,
  pooled = TRUE,
  correction = c("none", "hedges"),
  conf_level = 0.95
)

Arguments

Value

A list containing:

References

Cumming, G. (2014). The New Statistics. Psychol Sci 25(1):7-29. Hedges, L.V. (1981). J Educ Stat 6(2):107-128.

See Also

tTestEpochs() for significance testing, bootstrapCI() for bootstrap confidence intervals, rankBiserial() and cliffsDelta() for rank-based effect sizes.

Examples

# Create example epoched data
set.seed(123)
epochs <- array(rnorm(100 * 4 * 20 * 1), dim = c(100, 4, 20, 1))
pe <- PhysioExperiment(
  assays = list(epoched = epochs),
  samplingRate = 100
)
# Effect size for one-sample
result <- effectSize(pe, condition1 = 1:10)
# Hedges g between conditions
result2 <- effectSize(pe, condition1 = 1:10, condition2 = 11:20,
                      correction = "hedges")

Description

Calculates eigenvector centrality for each node.

Usage

eigenvectorCentrality(adjacency, max_iter = 100, tol = 1e-06, use_cpp = TRUE)

Arguments

Value

A numeric vector of eigenvector centrality values.

Examples

adj <- matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3, 3)
eigenvectorCentrality(adj)

Description

Functions for segmenting continuous data into epochs/trials based on events. Epoch data around events

Usage

epochData(
  x,
  tmin = -0.2,
  tmax = 0.8,
  event_type = NULL,
  baseline = NULL,
  reject = NULL,
  events = NULL,
  min_length = NULL
)

Arguments

Details

Extracts epochs (segments) of data around specified events.

Value

A new PhysioExperiment object with a 4D assay (time x channel x epoch x sample) named "epoched". Metadata includes epoch_tmin, epoch_tmax, epoch_info (a DataFrame with epoch_id, event_type, event_value, event_onset), and n_epochs.

References

Luck, S.J. (2014). "An Introduction to the Event-Related Potential Technique." 2nd ed. MIT Press.

See Also

averageEpochs() to average across epochs, epochTimes() to get the time vector, tTestEpochs() for statistical testing on epoched data, plotERP() for ERP visualization.

Examples

# Create continuous data with events
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000 * 4), nrow = 1000)),
  samplingRate = 100
)
pe <- addEvents(pe, onset = c(1, 2, 3, 4, 5), type = "stimulus")

# Extract epochs: 200ms before to 800ms after stimulus
epochs <- epochData(pe, tmin = -0.2, tmax = 0.8)

# With baseline correction
epochs_bl <- epochData(pe, tmin = -0.2, tmax = 0.8,
                       baseline = c(-0.2, 0))

# With artifact rejection
epochs_clean <- epochData(pe, tmin = -0.2, tmax = 0.8,
                          reject = 100)

Description

Segments continuous data into overlapping epochs using a sliding window approach. This is useful for time-frequency analysis or when events are not available.

Usage

epochSliding(x, window, step = NULL, baseline = NULL)

Arguments

Value

PhysioExperiment with epoched data

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000 * 4), nrow = 1000, ncol = 4)),
  samplingRate = 100)
# Create 0.5 second windows with 0.1 second step
epoched <- epochSliding(pe, window = 0.5, step = 0.1)

Description

Returns the time vector for epoched data relative to event onset.

Usage

epochTimes(x)

Arguments

Value

Numeric vector of times in seconds relative to event onset (negative values represent pre-stimulus time).

References

Luck, S.J. (2014). "An Introduction to the Event-Related Potential Technique." 2nd ed. MIT Press.

See Also

epochData() which creates the epoched data, averageEpochs() for epoch averaging, plotERP() for ERP visualization.

Description

Computes the discrete Fourier transform along the time axis of the default assay and stores the magnitude spectrum in a new assay named "fft".

Usage

fftSignals(x)

Arguments

Value

A PhysioExperiment object with an additional "fft" assay containing the magnitude spectrum (same dimensions as the input assay).

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

spectrogram() for time-frequency analysis, bandPower() for frequency band power extraction, plotPSD() for power spectral density visualization.

Description

Identifies contiguous time periods with significant effects.

Usage

findSignificantWindows(p_values, times = NULL, alpha = 0.05, min_duration = 0)

Arguments

Value

A data.frame with columns: start, end, duration, min_p.

References

Maris, E. & Oostenveld, R. (2007). "Nonparametric statistical testing of EEG- and MEG-data." Journal of Neuroscience Methods, 164(1), 177-190. doi:10.1016/j.jneumeth.2007.03.024

See Also

correctPValues() for multiple comparison correction, clusterPermutationTest() for cluster-based permutation testing, tTestEpochs() for pointwise t-tests.

Examples

# Example p-values
times <- seq(-0.2, 0.8, length.out = 100)
p <- c(rep(0.5, 30), rep(0.01, 20), rep(0.5, 50))
windows <- findSignificantWindows(p, times)

Description

The non-parametric repeated-measures omnibus test: compares k >= 2 matched treatments (columns) measured on the same N blocks/subjects (rows), by ranking within each block and testing whether the rank totals differ. It is the within-subject, distribution-free counterpart of the one-way ANOVA (oneWayAnova). The tie-corrected chi-square statistic and its p-value reproduce base R stats::friedman.test bit-for-bit and scipy.stats.friedmanchisquare to machine precision.

Usage

friedmanTest(x, ...)

Arguments

Value

A list with statistic (the tie-corrected Friedman chi-square), p_value, df (k - 1), k (treatments) and n (complete blocks).

See Also

oneWayAnova, pairedTTest

Examples

m <- matrix(rnorm(40) + rep(c(0, 0.5, 1, 1.5), each = 10), nrow = 10)
friedmanTest(m)

Description

Fits the subject random-intercept model to a set of curves nested in subjects. It splits the pointwise variance into between- and within-subject components (a functional ICC curve) and, when group is given, tests the between-subject fixed effect on the subject-mean curves so strides are not treated as independent.

Usage

functionalMixedModel(
  curves,
  subject,
  group = NULL,
  n_perm = 1000L,
  seed = NULL
)

Arguments

Value

a functional_mixed object: mean_curve, var_between, var_within, icc (functional ICC curve), subject_means (one row per subject), n_subjects, and – when group is given – f_curve, p_pointwise, p_global (subject-level fixed-effect test) plus group_diff (the signed difference curve for two groups).

References

Morris JS (2015) Functional regression, Annu Rev Stat Appl; Pini & Vantini (2017) interval-wise testing.

See Also

functionalRegression(), spmTTest()

Examples

set.seed(1)
P <- 101; t <- seq(0, 1, length.out = P)
make <- function(off) t(sapply(1:12, function(k) off + sin(2 * pi * t) + rnorm(P, 0, 0.1)))
ctrl <- do.call(rbind, lapply(rnorm(6, 0, 0.5), make))
pat  <- do.call(rbind, lapply(rnorm(6, 1.0, 0.5), make))   # shifted group
Y <- rbind(ctrl, pat)
subj <- rep(1:12, each = 12); grp <- rep(c("ctrl", "pat"), each = 72)
fm <- functionalMixedModel(Y, subj, grp, n_perm = 200)
fm$p_global                         # group difference, subject-level correct

Description

Models a set of response CURVES as a linear function of one or more scalar predictors, giving a coefficient curve for each predictor (how the waveform changes per unit predictor) with pointwise inference and a domain-wide permutation test.

Usage

functionalRegression(curves, predictor, n_perm = 1000L, seed = NULL)

Arguments

Value

a fosr_result: coefficients (⁠k x P⁠, incl. intercept), se, tval, p_pointwise (⁠k x P⁠), p_global (length k, family-wise), the fitted curves and terms.

References

Ramsay JO, Silverman BW (2005) Functional Data Analysis; Reiss PT, et al. (2010) function-on-scalar regression.

See Also

scalarOnFunctionRegression(), spmRegression()

Examples

set.seed(1)
P <- 101; t <- seq(0, 1, length.out = P)
speed <- runif(40, 0.8, 1.6)
curves <- outer(speed, rep(1, P)) * matrix(sin(2 * pi * t), 40, P, byrow = TRUE) +
  matrix(rnorm(40 * P, 0, 0.05), 40, P)
fit <- functionalRegression(curves, speed, n_perm = 200)
fit$p_global                       # speed coefficient curve is significant

Description

Calculates the global efficiency of a network.

Usage

globalEfficiency(adjacency, weighted = FALSE, use_cpp = TRUE)

Arguments

Value

Global efficiency value (0-1).

Examples

# Fully connected - maximum efficiency
adj <- matrix(1, 4, 4)
diag(adj) <- 0
globalEfficiency(adj)

Description

Computes grand average across multiple PhysioExperiment objects.

Usage

grandAverage(...)

Arguments

Value

A PhysioExperiment object with a "grand_average" assay containing the mean across all input objects. Metadata includes n_subjects indicating the number of objects averaged.

References

Luck, S.J. (2014). "An Introduction to the Event-Related Potential Technique." 2nd ed. MIT Press.

See Also

averageEpochs() for within-subject averaging, epochData() to create epoched data, plotERP() for ERP visualization.

Description

Calculates the graph Laplacian matrix.

Usage

graphLaplacian(adjacency, normalized = FALSE)

Arguments

Value

The Laplacian matrix.

Examples

adj <- matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3, 3)
L <- graphLaplacian(adj)

Description

Computes the analytic signal using the Hilbert transform. The analytic signal can be used to extract instantaneous amplitude and phase.

Usage

hilbertTransform(x, output_assay = "analytic")

Arguments

Value

A PhysioExperiment object with an additional assay (default "analytic") containing the complex-valued analytic signal.

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

instantaneousAmplitude() to extract the signal envelope, instantaneousPhase() to extract the instantaneous phase, plv() for phase-based connectivity.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(500 * 4), nrow = 500)),
  samplingRate = 100
)

# Compute Hilbert transform
pe <- hilbertTransform(pe)

# Extract amplitude and phase
pe <- instantaneousAmplitude(pe)
pe <- instantaneousPhase(pe)

Description

Extracts the instantaneous amplitude (envelope) from the analytic signal.

Usage

instantaneousAmplitude(x, assay_name = "analytic", output_assay = "amplitude")

Arguments

Value

A PhysioExperiment object with an additional assay (default "amplitude") containing the real-valued instantaneous amplitude (envelope) of the signal.

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

hilbertTransform() which must be called first, instantaneousPhase() for the companion phase extraction, waveletTransform() for alternative time-frequency decomposition.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(500 * 4), nrow = 500)),
  samplingRate = 100
)

# First compute Hilbert transform, then extract amplitude
pe <- hilbertTransform(pe)
pe <- instantaneousAmplitude(pe)

Description

Extracts the instantaneous phase from the analytic signal.

Usage

instantaneousPhase(x, assay_name = "analytic", output_assay = "phase")

Arguments

Value

A PhysioExperiment object with an additional assay (default "phase") containing instantaneous phase values in radians (range $[-\pi, \pi]$).

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

hilbertTransform() which must be called first, instantaneousAmplitude() for the companion amplitude extraction, plv() for phase-based connectivity analysis.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(500 * 4), nrow = 500)),
  samplingRate = 100
)

# First compute Hilbert transform, then extract phase
pe <- hilbertTransform(pe)
pe <- instantaneousPhase(pe)

Description

Computes the interquartile range (IQR) of a one-dimensional signal – the spread of the middle 50%, $Q_3 - Q_1$ – a robust, quantile-based measure of dispersion that ignores the tails entirely. The quartiles use R's default type-7 quantile (the same linear interpolation as scipy.stats.iqr and numpy.percentile), so the result matches both bit-for-bit.

Usage

interquartileRange(x, type = 7L)

Arguments

Details

A quantile-based robust spread that complements medianAbsDev (a deviation-based robust scale) and signalMoments (the classical SD). For approximately Gaussian data, $\mathrm{IQR} / (2\,\Phi^{-1}(0.75))$ ($\approx \mathrm{IQR}/1.349$) is a robust estimate of the SD; a value well below the SD flags a skewed or heavy-tailed distribution.

Value

A single numeric value, the interquartile range.

See Also

medianAbsDev for the deviation-based robust scale, signalMoments for the classical moments.

Examples

interquartileRange(c(1, 2, 3, 4, 100))   # robust to the outlier
interquartileRange(rnorm(1000)) / 1.349  # ~1 (robust SD estimate)

Description

The six McGraw & Wong (1996) intraclass correlation coefficients from a subjects-by-raters (or subjects-by-repeated-measurements) matrix: ICC1, ICC2, ICC3 (single measurement) and ICC1k, ICC2k, ICC3k (average of k measurements). The standard index of test-retest / inter-rater reliability, computed from a two-way ANOVA. Reproduces the psych package (psych::ICC(lmer = FALSE)) to machine precision and pingouin.intraclass_corr bit-for-bit.

Usage

intraclassCorrelation(x)

Arguments

Value

A data frame with one row per ICC form (form, ICC), carrying n (subjects) and k (raters/measurements) as attributes.

Examples

m <- matrix(rnorm(30), ncol = 3) + rnorm(10)
intraclassCorrelation(m)

Description

Applies the Jarque-Bera goodness-of-fit test for normality (Jarque & Bera, 1980) to a one-dimensional signal: the statistic $JB = \frac{N}{6}\left(S^2 + \frac{K^2}{4}\right)$, where $S$ is the skewness and $K$ the excess kurtosis (from signalMoments), is compared to a chi-squared distribution with 2 degrees of freedom. It is the formal, moment-based counterpart of the descriptive near-Gaussian check: a large statistic rejects normality. Same definition as scipy.stats.jarque_bera.

Usage

jarqueBeraTest(x)

Arguments

Value

A list with statistic (the JB statistic), p_value (the chi-squared upper-tail probability), and df (2).

References

Jarque, C.M., Bera, A.K. (1980). Efficient tests for normality, homoscedasticity and serial independence of regression residuals. Economics Letters, 6(3), 255-259.

See Also

signalMoments

Examples

set.seed(1)
jarqueBeraTest(rnorm(1000))$p_value   # Gaussian -> large p (fail to reject)

Description

Kendall's tau-b, the concordance-based rank correlation: the normalised difference between concordant and discordant pairs, tie-corrected. It is the third rank-correlation method alongside Pearson's r (correlationTest, method "pearson") and Spearman's rho (method "spearman"), and is the robust choice for ordinal or heavily-tied data and small samples. The tau-b statistic and the normal-approximation p-value reproduce base R stats::cor.test(method = "kendall") and scipy.stats.kendalltau bit-for-bit.

Usage

kendallTau(x, y = NULL)

Arguments

Value

A list with statistic (tau-b), p_value (two-sided, normal-approximation), z (the approximation's z-statistic) and n.

See Also

correlationTest

Examples

kendallTau(c(1, 2, 3, 4, 5), c(2, 1, 4, 3, 5))

Description

Computes the KPSS statistic (Kwiatkowski, Phillips, Schmidt & Shin, 1992) for level stationarity of a one-dimensional signal. The residuals from regressing the signal on a constant are cumulatively summed, and the statistic is $\eta = N^{-2}\sum_t S_t^2 / \hat\lambda^2$, where $S_t$ are the partial sums and $\hat\lambda^2$ is a Bartlett (Newey-West) long-run variance estimate with truncation lag. Unlike the Augmented Dickey-Fuller test, the KPSS null is stationarity: a small statistic (below the critical value) means the series is consistent with stationarity. The statistic is the same deterministic quantity as statsmodels.tsa.stattools.kpss(regression = "c", nlags = lag).

Usage

kpssTest(x, lag = 10L)

Arguments

Details

Note: only the statistic is computed here (an exact quantity). The KPSS critical values and p-value come from the reference tables (an approximation) and are not returned.

Value

A list with statistic (the KPSS $\eta$), n (the signal length), and lag.

References

Kwiatkowski, D., Phillips, P.C.B., Schmidt, P., Shin, Y. (1992). Testing the null hypothesis of stationarity against the alternative of a unit root. Journal of Econometrics, 54(1-3), 159-178.

See Also

adfTest, autocorrelation

Examples

set.seed(1)
kpssTest(rnorm(500), lag = 10)$statistic   # stationary -> small statistic

Description

The non-parametric between-groups omnibus test: pools all observations, ranks them, and tests whether the rank totals differ across k >= 2 independent groups. It is the distribution-free counterpart of the one-way ANOVA (oneWayAnova) and, unlike it, makes no normality or equal-variance assumption. The tie-corrected statistic and its p-value reproduce base R stats::kruskal.test bit-for-bit (the H is accumulated in the same order) and scipy.stats.kruskal to machine precision.

Usage

kruskalTest(x, ...)

Arguments

Value

A list with statistic (the tie-corrected H), p_value, df (k - 1), k (number of groups) and n (total sample size).

See Also

oneWayAnova, friedmanTest

Examples

kruskalTest(list(rnorm(20), rnorm(20, 1), rnorm(20, 2)))

Description

Tests whether a one-dimensional signal is normally distributed by comparing its empirical cumulative distribution function (ECDF) to that of a normal distribution fitted to the sample (mean and SD). The statistic is the Kolmogorov-Smirnov distance $D = \sup_x |F_n(x) - \Phi((x-\mu)/\sigma)|$, the largest vertical gap between the two CDFs; the two-sided asymptotic (Kolmogorov) p-value follows. The $D$ statistic reproduces stats::ks.test and scipy.stats.kstest bit-for-bit.

Usage

ksNormalityTest(x)

Arguments

Details

A distribution-shape (empirical-CDF) normality test, complementary to the moment-based jarqueBeraTest: KS responds to the overall shape of the distribution, Jarque-Bera to its skewness and kurtosis (the tails). The two can disagree – on a long, mildly non-Gaussian signal Jarque-Bera's power often rejects while KS does not.

Value

A list with statistic (the KS distance $D$), p_value (two-sided asymptotic), and n (sample size).

Caveat

Because the normal parameters are estimated from the same sample, the naive p-value is anti-conservative (a Lilliefors correction gives an exact test); the $D$ statistic itself is exact and is what this function certifies.

See Also

jarqueBeraTest for the moment-based normality test, signalMoments for the skewness and kurtosis.

Examples

set.seed(1); ksNormalityTest(rnorm(500))$p_value    # Gaussian -> large p
set.seed(1); ksNormalityTest(rexp(500))$statistic   # skewed -> large D

Description

Levene's test of whether k >= 2 groups have equal variance, as a one-way ANOVA on the absolute deviations from each group's centre. With center = "median" (default) it is the robust Brown-Forsythe variant, appropriate when the data may be non-normal; center = "mean" is the classic Levene test. The F-statistic and p reproduce scipy.stats.levene and the car package (car::leveneTest) bit-for-bit.

Usage

leveneTest(x, ..., center = c("median", "mean"))

Arguments

Value

A list with statistic (F), p_value, df1 (k - 1), df2 (N - k), k, n and center.

See Also

oneWayAnova

Examples

leveneTest(list(rnorm(20), rnorm(20, 0, 2), rnorm(20, 0, 0.5)))

Description

Univariate OLS regression of y on x: the slope, intercept, R-squared, and the two-sided t-test of the slope. The slope, R-squared and p-value reproduce base R stats::lm / summary.lm and scipy.stats.linregress bit-for-bit (to machine precision against lm's QR path).

Usage

linearRegression(x, y = NULL)

Arguments

Value

A list with slope, intercept, r_squared, statistic (the slope t-statistic), p_value (two-sided), df (n - 2) and n.

See Also

correlationTest

Examples

linearRegression(1:20, 2 * (1:20) + rnorm(20))

Description

Applies the Ljung-Box portmanteau test (Ljung & Box, 1978) to a one-dimensional signal: the statistic $Q = N(N+2)\sum_{k=1}^{h} \hat\rho_k^2 / (N-k)$ aggregates the first lag squared autocorrelations (from autocorrelation), and under the null hypothesis that the series is white noise $Q$ follows a chi-squared distribution with lag degrees of freedom. It is the standard formal test for the presence of autocorrelation (and, applied to model residuals, for model adequacy). Same definition as statsmodels.stats.diagnostic.acorr_ljungbox and stats::Box.test(type = "Ljung-Box").

Usage

ljungBoxTest(x, lag = 10L)

Arguments

Value

A list with statistic (the Ljung-Box $Q$), p_value (the chi-squared upper-tail probability), and df (= lag).

References

Ljung, G.M., Box, G.E.P. (1978). On a measure of lack of fit in time series models. Biometrika, 65(2), 297-303.

See Also

autocorrelation, Box.test

Examples

set.seed(1)
ljungBoxTest(rnorm(500), lag = 10)$p_value   # white noise -> large p

Description

Calculates the local efficiency for each node.

Usage

localEfficiency(adjacency, weighted = FALSE)

Arguments

Value

A numeric vector of local efficiency values.

Examples

adj <- matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3, 3)
localEfficiency(adj)

Description

Computes the median absolute deviation (MAD) of a one-dimensional signal – $\mathrm{MAD} = c \cdot \mathrm{median}(|x - \mathrm{median}(x)|)$ – a robust measure of dispersion that, unlike the standard deviation, is not inflated by a small number of extreme values (spikes, movement artifacts). With the default constant = 1 it returns the raw MAD; set constant = 1 / stats::qnorm(0.75) (approximately 1.4826) to obtain the normal-consistent robust estimate of the standard deviation (the scale MAD and SD share for Gaussian data).

Usage

medianAbsDev(x, constant = 1)

Arguments

Details

The robust dispersion companion of signalMoments (whose SD is the classical, non-robust dispersion). Comparing the normal-consistent MAD with the SD is a quick artifact check: they agree for clean, near-Gaussian data and diverge (MAD-scale below SD) when heavy-tailed artifacts inflate the SD.

Value

A single numeric value, the (scaled) median absolute deviation.

See Also

signalMoments for the classical moments (mean, SD, skewness, kurtosis).

Examples

medianAbsDev(c(1, 2, 3, 4, 100))                         # robust to the outlier
set.seed(1); medianAbsDev(rnorm(1000), 1 / stats::qnorm(0.75))  # ~1 (robust SD)

Description

Calculates the modularity of a network given a community partition.

Usage

modularity(adjacency, communities)

Arguments

Value

Modularity value (-0.5 to 1).

Examples

# Two clear communities
adj <- matrix(0, 6, 6)
adj[1:3, 1:3] <- 1
adj[4:6, 4:6] <- 1
diag(adj) <- 0
communities <- c(1, 1, 1, 2, 2, 2)
modularity(adj, communities)

Description

Multivariable OLS regression of a response on two or more predictors: the coefficient table (estimate, standard error, t-statistic, p-value) plus the overall model fit (R-squared, adjusted R-squared and the F-test). The many-predictor generalisation of linearRegression. Computed via the same QR decomposition as base R, so the coefficients, R-squared and F reproduce stats::lm / summary.lm bit-for-bit and statsmodels OLS to machine precision.

Usage

multipleRegression(x)

Arguments

Value

A data frame with one row per term (term, estimate, std_error, statistic, p_value), carrying r_squared, adj_r_squared, f_statistic, df1, df2, f_p_value and n as attributes.

See Also

linearRegression, partialCorrelation

Examples

x <- matrix(rnorm(120), ncol = 3); colnames(x) <- c("y", "a", "b")
multipleRegression(x)

Description

The Nemenyi test: all pairwise comparisons of the treatments following a Friedman repeated-measures test (friedmanTest), from the within-block mean ranks and the studentized-range distribution with single-step control of the family-wise error rate. It is the repeated-measures counterpart of Tukey's HSD (tukeyHSD) and Dunn's test (dunnTest). The statistics and p-values reproduce base R's Nemenyi formula, the PMCMRplus package and scikit_posthocs.posthoc_nemenyi_friedman to machine precision.

Usage

nemenyiTest(x)

Arguments

Value

A data frame with one row per pair: comparison, statistic and p_adj, carrying k (treatments) and n (complete blocks) as attributes.

See Also

friedmanTest, tukeyHSD, dunnTest

Examples

m <- matrix(rnorm(40) + rep(c(0, 0.5, 1, 1.5), each = 10), nrow = 10)
colnames(m) <- c("a", "b", "c", "d"); nemenyiTest(m)

Description

Identifies connected subnetworks of edges that differ between two groups (or two within-subject conditions) of connectivity matrices, with family-wise error control from a permutation null on the largest suprathreshold component (Zalesky, Fornito & Bullmore 2010). Each edge is first tested with a mass-univariate t-test; edges whose statistic exceeds thresh form a suprathreshold graph whose connected components are the candidate subnetworks. Their size (edge count) or mass (summed statistic exceedance, Smith 2009) is compared against the permutation distribution of the largest component to obtain FWER-corrected component p-values.

Usage

networkBasedStatistic(
  mats_group1,
  mats_group2,
  thresh = 3,
  n_perm = 1000L,
  tail = c("both", "right", "left"),
  paired = FALSE,
  component = c("size", "mass"),
  directed = FALSE,
  alpha = 0.05,
  seed = NULL
)

Arguments

Value

A list with components (a data.frame of component size, mass, and p_value), component_edges (a list of node-pair matrices, one per component), the adjacency mask of edges in significant components, the edge_stats matrix, the suprathreshold mask, the permutation null_distribution, and the settings used.

References

Zalesky, A., Fornito, A., & Bullmore, E. T. (2010). Network-based statistic: identifying differences in brain networks. NeuroImage, 53(4), 1197-1207.

See Also

plotNBSnetwork()

Examples

## Not run: 
g1 <- replicate(20, matrix(rnorm(400), 20), simplify = FALSE)
g2 <- replicate(20, matrix(rnorm(400), 20), simplify = FALSE)
nbs <- networkBasedStatistic(g1, g2, thresh = 3, n_perm = 500)
nbs$components

## End(Not run)

Description

Calculates the degree (number of connections) for each node.

Usage

nodeDegree(adjacency, weighted = FALSE, use_cpp = TRUE)

Arguments

Value

A numeric vector of node degrees.

Examples

adj <- matrix(c(0, 1, 1, 1, 0, 0, 1, 0, 0), 3, 3)
nodeDegree(adj)

Description

Classic one-way analysis of variance (equal-variance omnibus F-test) comparing the means of k >= 2 independent groups. The F-statistic and its p-value reproduce base R stats::oneway.test(var.equal = TRUE) and scipy.stats.f_oneway bit-for-bit. This is the standard many-group generalisation of the independent two-sample t-test (twoSampleTTest).

Usage

oneWayAnova(x, ...)

Arguments

Value

A list with statistic (the F-ratio), p_value, df1 (between-groups degrees of freedom, k - 1), df2 (within-groups, N - k), k (number of groups) and n (total sample size).

See Also

twoSampleTTest, pairedTTest

Examples

oneWayAnova(list(rnorm(20), rnorm(20, 1), rnorm(20, 2)))

Description

Computes the two-sided paired-samples t-test comparing two matched vectors – the one-sample t-test of the within-pair differences $d = x - y$: $t = \bar{d} / (s_d / \sqrt{n})$ on $n - 1$ degrees of freedom. The standard test for before/after or condition-A/condition-B measurements on the same subjects. Reproduces stats::t.test(x, y, paired = TRUE) and scipy.stats.ttest_rel bit-for-bit.

Usage

pairedTTest(x, y = NULL)

Arguments

Value

A list with statistic (the t-statistic of $x - y$), p_value (two-sided) and df.

See Also

signalMoments, jarqueBeraTest.

Examples

set.seed(1); pairedTTest(rnorm(20, 1), rnorm(20))$statistic  # x shifted up -> positive t

Description

Computes the sample partial autocorrelation function of a one-dimensional signal at lags 0, 1, ..., lag_max. The partial autocorrelation at lag $k$ is the correlation between $x_t$ and $x_{t+k}$ with the linear effect of the intervening lags removed, obtained here by the Durbin-Levinson recursion on the biased, demeaned autocorrelation sequence (via autocorrelation) – the same definition as stats::pacf and statsmodels.tsa.pacf(method = "ldb"). Where the ACF decays, the PACF cuts off after the autoregressive order, so it is the standard tool for choosing AR model order.

Usage

partialAutocorrelation(x, lag_max = 20L)

Arguments

Value

A numeric vector of partial autocorrelation coefficients at lags 0:lag_max; the lag-0 value is 1 by convention and the lag-1 value equals the lag-1 autocorrelation.

References

Box, G.E.P., Jenkins, G.M. (1976). Time Series Analysis: Forecasting and Control. Holden-Day.

See Also

autocorrelation, pacf

Examples

set.seed(1)
partialAutocorrelation(as.numeric(arima.sim(list(ar = 0.6), 500)), lag_max = 10)

Description

The correlation between x and y after linearly removing one or more covariates z from both – the standard tool for asking whether an association survives adjustment for a confound. With method = "spearman" the variables are rank-transformed first (a rank / robust partial correlation). The coefficient reproduces base R's residual method and the ppcor package to machine precision.

Usage

partialCorrelation(x, y = NULL, z = NULL, method = c("pearson", "spearman"))

Arguments

Value

A list with statistic (the partial correlation), p_value (two-sided t-test), df (n - 2 - k), n and k (number of covariates).

See Also

correlationTest, kendallTau

Examples

x <- rnorm(50); z <- rnorm(50); y <- 0.5 * z + rnorm(50)
partialCorrelation(x, y, z)

Description

Calculates the shortest path length between all node pairs using Floyd-Warshall.

Usage

pathLength(adjacency, weighted = FALSE, use_cpp = TRUE)

Arguments

Value

A matrix of shortest path lengths.

Examples

adj <- matrix(c(0, 1, 0, 1, 0, 1, 0, 1, 0), 3, 3)
pathLength(adj)

Description

Calculates the Phase Lag Index between channel pairs, a measure of asymmetry in the phase difference distribution.

Usage

pli(x, freq_band, channels = NULL, assay_name = NULL)

Arguments

Details

PLI measures the asymmetry of the distribution of phase differences. Unlike PLV, PLI is insensitive to volume conduction effects that lead to zero-lag synchronization.

PLI = |mean(sign(Im(S_xy)))|, where S_xy is the cross-spectrum.

Value

A numeric matrix of PLI values (channel x channel) with values ranging from 0 (no asymmetry in phase distribution) to 1 (maximal asymmetry). Row and column names are set to channel names when available.

References

Lachaux, J.-P., et al. (1999). "Measuring phase synchrony in brain signals." Human Brain Mapping, 8(4), 194-208. doi:10.1002/(SICI)1097-0193(1999)8:4<194::AID-HBM4>3.0.CO;2-C

See Also

plv() for phase locking value, wPLI() for weighted phase lag index, coherence() for frequency-domain coherence, connectivityMatrix() for a unified connectivity interface.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(4000), nrow = 1000, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 256
)

# Compute PLI in alpha band (8-12 Hz)
pli_matrix <- pli(pe, freq_band = c(8, 12))

Description

Creates a heatmap visualization of an adjacency or connectivity matrix.

Usage

plotAdjacencyMatrix(
  adjacency,
  node_names = NULL,
  symmetric = TRUE,
  color_palette = "default",
  show_values = FALSE,
  title = "Connectivity Matrix"
)

Arguments

Value

A ggplot object.

Examples

set.seed(123)
adj <- matrix(runif(16), 4, 4)
adj <- (adj + t(adj)) / 2
diag(adj) <- 1
plotAdjacencyMatrix(adj, node_names = c("Fz", "Cz", "Pz", "Oz"))

Description

Creates a visualization of time-varying connectivity.

Usage

plotDynamicConnectivity(
  dyn_conn,
  node_pair = "mean",
  title = "Dynamic Connectivity"
)

Arguments

Value

A ggplot object.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000 * 4), nrow = 1000, ncol = 4)),
  samplingRate = 100
)
dyn_conn <- slidingWindowConnectivity(pe, window_size = 200, step = 50)
plotDynamicConnectivity(dyn_conn, node_pair = c(1, 2))

Description

Generates an ERP plot from epoched data.

Usage

plotERP(x, channel = 1L, ci = 0.95, show_epochs = FALSE, epoch_alpha = 0.2)

Arguments

Value

A ggplot object.

References

Wickham, H. (2016). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. doi:10.1007/978-3-319-24277-4

Delorme, A. & Makeig, S. (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics including independent component analysis." Journal of Neuroscience Methods, 134(1), 9-21. doi:10.1016/j.jneumeth.2003.10.009

See Also

plotMultiChannel() for multi-channel visualization, plotTopomap() for topographic maps, epochData() for creating epoched data, bootstrapCI() for bootstrap confidence intervals.

Description

Functions for visualizing multiple channels simultaneously. Plot multiple channels (butterfly or stacked)

Usage

plotMultiChannel(
  x,
  channels = NULL,
  sample = 1L,
  style = c("butterfly", "stacked"),
  offset = NULL,
  assay_name = NULL,
  colors = NULL
)

Arguments

Details

Generates a plot showing multiple channels from the signal data.

Value

A ggplot object.

References

Wickham, H. (2016). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. doi:10.1007/978-3-319-24277-4

Delorme, A. & Makeig, S. (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics including independent component analysis." Journal of Neuroscience Methods, 134(1), 9-21. doi:10.1016/j.jneumeth.2003.10.009

See Also

plotSignal() for single-channel plots, plotERP() for event-related potential plots, plotTopomap() for topographic visualization.

Examples

# Create example data
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(500 * 4), nrow = 500)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)

# Butterfly plot (all channels overlaid)
plotMultiChannel(pe, style = "butterfly")

# Stacked plot (channels offset vertically)
plotMultiChannel(pe, style = "stacked")

# Plot specific channels
plotMultiChannel(pe, channels = c(1, 3), style = "butterfly")

Description

Draws the edges belonging to significant NBS components on a circular node layout.

Usage

plotNBSnetwork(
  result,
  alpha = NULL,
  node_labels = NULL,
  title = "NBS subnetwork"
)

Arguments

Value

A ggplot object.

See Also

networkBasedStatistic()

Examples

## Not run: 
plotNBSnetwork(networkBasedStatistic(g1, g2))

## End(Not run)

Description

Functions for visualizing functional connectivity networks including network graphs, adjacency matrices, and network metrics. Plot network graph

Usage

plotNetwork(
  adjacency,
  node_names = NULL,
  node_size = "degree",
  edge_threshold = 0,
  layout = c("circle", "spring", "grid"),
  node_color = "#3498db",
  edge_color = "#7f8c8d",
  title = "Network Graph"
)

Arguments

Details

Creates a network graph visualization with nodes and edges.

Value

A ggplot object.

Examples

set.seed(123)
adj <- matrix(runif(16), 4, 4)
adj <- (adj + t(adj)) / 2
diag(adj) <- 0
plotNetwork(adj, node_names = c("Fz", "Cz", "Pz", "Oz"))

Description

Creates a bar plot of network metrics for each node.

Usage

plotNetworkMetrics(
  adjacency,
  metrics = c("degree", "clustering", "betweenness"),
  node_names = NULL,
  title = "Network Metrics"
)

Arguments

Value

A ggplot object.

Examples

adj <- matrix(c(0, 1, 1, 1, 1, 0, 1, 0, 1, 1, 0, 1, 1, 0, 1, 0), 4, 4)
plotNetworkMetrics(adj, node_names = c("Fz", "Cz", "Pz", "Oz"))

Description

Visualizes the temporal stability of network topology.

Usage

plotNetworkStability(stability, title = "Network Stability")

Arguments

Value

A ggplot object.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000 * 4), nrow = 1000, ncol = 4)),
  samplingRate = 100
)
dyn_conn <- slidingWindowConnectivity(pe, window_size = 200, step = 50)
stab <- temporalStability(dyn_conn)
plotNetworkStability(stab)

Description

Generates a PSD plot for specified channels.

Usage

plotPSD(x, channels = NULL, sample = 1L, log_scale = TRUE, freq_range = NULL)

Arguments

Value

A ggplot object.

References

Wickham, H. (2016). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. doi:10.1007/978-3-319-24277-4

Delorme, A. & Makeig, S. (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics including independent component analysis." Journal of Neuroscience Methods, 134(1), 9-21. doi:10.1016/j.jneumeth.2003.10.009

See Also

plotSignal() for time-domain signal plots, fftSignals() for FFT computation, bandPower() for frequency band power extraction, plotSpectrogram() for time-frequency visualization.

Description

Generates a simple line plot for the selected channel and sample from the default assay. Supports both 2D (time x channel) and 3D (time x channel x sample) assay arrays.

Usage

plotSignal(x, channel = 1L, sample = 1L, assay_name = NULL)

Arguments

Value

A ggplot object.

References

Wickham, H. (2016). ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York. doi:10.1007/978-3-319-24277-4

See Also

plotMultiChannel() for multi-channel visualization, plotPSD() for power spectral density plots, plotERP() for event-related potential plots.

Description

Plots the observed log power spectrum for one channel together with the full specparam model and the aperiodic-only fit.

Usage

plotSpecparam(result, channel = 1)

Arguments

Value

A ggplot object.

See Also

specparam()

Examples

## Not run: 
sp <- specparam(make_pe_2d(n_time = 4000, sr = 250))
plotSpecparam(sp, channel = 1)

## End(Not run)

Description

Creates a visualization of a spectrogram result.

Usage

plotSpectrogram(spec, freq_range = NULL, log_power = TRUE)

Arguments

Value

A ggplot object showing the spectrogram as a filled raster plot with time on the x-axis and frequency on the y-axis.

References

Oppenheim, A.V. & Willsky, A.S. (1997). "Signals and Systems." 2nd ed. Prentice Hall.

See Also

spectrogram() to compute the spectrogram data, plotPSD() for power spectral density plots, plotSignal() for time-domain visualization.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000 * 4), nrow = 1000)),
  samplingRate = 250
)

# Compute spectrogram
spec <- spectrogram(pe, channel = 1)

# Plot with frequency range filter
plotSpectrogram(spec, freq_range = c(1, 50))

Description

Visualizes SPM analysis results with significance thresholds.

Usage

plotSPM(
  x,
  time_axis = NULL,
  show_threshold = TRUE,
  show_clusters = TRUE,
  title = NULL
)

Arguments

Value

A ggplot object.

Examples

# Create and plot SPM result
set.seed(123)
g1 <- matrix(rnorm(100 * 10), nrow = 100)
g2 <- matrix(rnorm(100 * 10), nrow = 100)
g2[40:60, ] <- g2[40:60, ] + 1.5

pe <- PhysioExperiment(
  assays = list(values = cbind(g1, g2)),
  samplingRate = 100
)
result <- spmTTest(pe, group1 = 1:10, group2 = 11:20)
plotSPM(result)

Description

Functions for plotting scalp topography maps showing the spatial distribution of signal values across electrode positions. Plot topographic map (scalp topography)

Usage

plotTopomap(
  x,
  values = NULL,
  time = NULL,
  channel_values = NULL,
  assay_name = NULL,
  resolution = 100L,
  contours = TRUE,
  head_shape = TRUE,
  electrodes = TRUE,
  palette = "RdBu",
  limits = NULL,
  title = NULL,
  interpolation = c("idw", "spline"),
  spline_stiffness = 4L,
  spline_terms = 50L,
  spline_regularization = 0
)

Arguments

Details

Creates a 2D topographic map showing the spatial distribution of values across electrode positions on the scalp.

With interpolation = "idw", scalp values are interpolated by inverse distance weighting (Shepard's method) with power 2. With interpolation = "spline", planar montage coordinates are lifted to a shared upper unit hemisphere and evaluated with the Perrin spherical-spline kernel. This is spatial interpolation, not a surface Laplacian, current-source-density estimate, reference transformation, or source localization.

Value

A ggplot object.

References

Shepard, D. (1968). "A two-dimensional interpolation function for irregularly-spaced data." Proceedings of the 1968 23rd ACM National Conference, 517-524. doi:10.1145/800186.810616

Perrin F, Pernier J, Bertrand O, Echallier J. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography and Clinical Neurophysiology, 72(2), 184-187. doi:10.1016/0013-4694(89)90180-6

See Also

plotTopomapSeries() for topographic maps across time, plotMultiChannel() for multi-channel signal visualization, plotERP() for event-related potential plots.

Examples

# Create example with 10-20 electrode positions
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)

# Apply 10-20 montage to get electrode positions
pe <- applyMontage(pe, "10-20")

# Plot topographic map at time = 0.5s
plotTopomap(pe, time = 0.5)

# Plot with custom values
plotTopomap(pe, values = c(1, 0.5, -0.5, -1))

Description

Creates a series of topographic maps across time.

Usage

plotTopomapSeries(x, times, ...)

Arguments

Details

The interpolation method and controls are forwarded unchanged to plotTopomap().

Value

A list of ggplot objects.

References

Shepard, D. (1968). "A two-dimensional interpolation function for irregularly-spaced data." Proceedings of the 1968 23rd ACM National Conference, 517-524. doi:10.1145/800186.810616

Perrin F, Pernier J, Bertrand O, Echallier J. (1989). Spherical splines for scalp potential and current density mapping. Electroencephalography and Clinical Neurophysiology, 72(2), 184-187. doi:10.1016/0013-4694(89)90180-6

See Also

plotTopomap() for a single topographic map, plotERP() for event-related potential plots, plotMultiChannel() for multi-channel signal visualization.

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)
pe <- applyMontage(pe, "10-20")

# Create topomaps at multiple time points
plots <- plotTopomapSeries(pe, times = c(0.1, 0.2, 0.3, 0.4))

Description

Calculates the Phase Locking Value between channel pairs, measuring the consistency of phase difference across time.

Usage

plv(x, freq_band, channels = NULL, assay_name = NULL)

Arguments

Details

PLV measures the consistency of the phase difference between two signals. A value of 1 indicates perfect phase locking, while 0 indicates random phase relationship.

The signals are first bandpass filtered to the specified frequency band, then the analytic signal is computed using the Hilbert transform.

Value

A numeric matrix of PLV values (channel x channel) with values ranging from 0 (random phase relationship) to 1 (perfect phase locking). Row and column names are set to channel names when available.

References

Lachaux, J.-P., et al. (1999). "Measuring phase synchrony in brain signals." Human Brain Mapping, 8(4), 194-208. doi:10.1002/(SICI)1097-0193(1999)8:4<194::AID-HBM4>3.0.CO;2-C

See Also

pli() for phase lag index, wPLI() for weighted phase lag index, coherence() for frequency-domain coherence, connectivityMatrix() for a unified connectivity interface.

Examples

set.seed(123)
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(4000), nrow = 1000, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 256
)

# Compute PLV in alpha band (8-12 Hz)
plv_matrix <- plv(pe, freq_band = c(8, 12))