Skip to contents

Modulation-index comodulogram with surrogate inference

Source: R/coupling-pac.R
modulationIndex.Rd

Computes Tort, Canolty, or Ozkurt phase-amplitude coupling over a declared frequency grid. Each surrogate amplitude-source signal produces one complete matrix, so cell-wise p-values share a coherent null replicate. P-values use the conservative Phipson-Smyth correction and are adjusted over the complete grid.

Usage

modulationIndex(
  x,
  phase_freqs,
  amp_freqs,
  sr = NULL,
  y = NULL,
  method = c("tort", "canolty", "ozkurt"),
  phase_bw = 2,
  amp_bw = 10,
  n_bins = 18L,
  order = 4L,
  n_surrogates = 199L,
  surrogate_type = c("timeshift", "phase", "iaaft", "aaft"),
  alpha = 0.05,
  p_adjust_method = "BH",
  seed = NULL,
  cores = 1L,
  modality_x = NULL,
  modality_y = NULL,
  channels_x = 1L,
  channels_y = 1L
)

Arguments

x

A numeric signal or PhysioExperiment providing the phase source, or a MultiPhysioExperiment.

phase_freqs

Strictly increasing phase-band centre frequencies in Hz.

amp_freqs

Strictly increasing amplitude-band centre frequencies in Hz.

sr

Sampling rate in Hz, required for numeric input.

y

Optional amplitude-source signal or PhysioExperiment. When NULL, a non-MultiPhysioExperiment x supplies both sources.

method

"tort", "canolty", or "ozkurt".

phase_bw, amp_bw

Half-bandwidths in Hz.

n_bins

Number of phase bins for Tort MI.

order

Bandpass filter order.

n_surrogates

Number of full-grid surrogates. Use zero to disable inference explicitly.

surrogate_type

"timeshift", "phase", "iaaft", or "aaft".

alpha

Significance level.

p_adjust_method

A method from stats::p.adjust.methods, applied once across the complete frequency grid.

seed

Optional non-negative integer seed.

cores

Positive integer number of worker processes.

modality_x, modality_y, channels_x, channels_y

Passed to the shared signal-pair extractor.

Value

A pac_comodulogram list containing the observed matrix, grid and realized bands, peak, cell-wise p-values, adjusted p-values, significance mask, null thresholds and summaries, surrogate settings, and structured diagnostic strings. Inferential matrices are NULL when n_surrogates = 0.

Details

PAC is an association and can be produced by waveform shape, filter leakage, edge transients, non-stationarity, or common inputs. A high or significant value does not establish cross-frequency communication or a biological mechanism. The returned threshold is the unadjusted cell-wise null quantile; the significant mask is instead defined from adjusted p-values. Benjamini-Hochberg controls the false discovery rate, not strong family-wise error. Requested and exact realized pass bands are both retained; a structured diagnostic records any adjustment at the filter's numerical boundary.

References

Tort, A. B. L., et al. (2010). Journal of Neurophysiology, 104, 1195-1210.

Canolty, R. T., et al. (2006). Science, 313, 1626-1628.

Ozkurt, T. E., & Schnitzler, A. (2011). Journal of Neuroscience Methods, 201, 438-443.

Phipson, B., & Smyth, G. K. (2010). Statistical Applications in Genetics and Molecular Biology, 9, Article 39.

See also

comodulogram(), phaseAmplitudeCoupling(), plotComodulogram()

Examples

if (FALSE) { # \dontrun{
set.seed(1)
t <- (0:4999) / 500
ph <- 2 * pi * 6 * t
sig <- sin(ph) + (0.1 + (1 + cos(ph - pi)) / 2) * sin(2 * pi * 50 * t)
mi <- modulationIndex(sig, c(4, 6, 8), c(40, 50, 60), sr = 500,
                      n_surrogates = 99, seed = 1)
plotComodulogram(mi)
} # }