Epochs#

Epochs around events#

Event-locked analysis – spikes, stimuli, spindles – for a review viewer’s “epoch average” and for scripts:

  • extract_epochs() – cut fixed windows around event times;

  • epoch_average() – mean and standard error;

  • cluster_permutation_test() – where in time does the average differ from zero, or two conditions from each other (Maris & Oostenveld, 2007), with the family-wise error controlled over the whole window;

  • ersp_itc() – event-related spectral perturbation and inter-trial coherence from complex Morlet wavelets.

An epoch that would run past either end of the record, or that holds any NaN/inf, is dropped rather than padded: the returned kept mask says which events were used.

class brainmaze_eeg.epochs.Cluster(start: int, stop: int, stat: float, p: float)#

A run of time bins [start, stop) past the threshold, its summed t, and its permutation p-value (family-wise over the window).

p: float#

Alias for field number 3

start: int#

Alias for field number 0

stat: float#

Alias for field number 2

stop: int#

Alias for field number 1

brainmaze_eeg.epochs.cluster_permutation_test(a, b=None, n_permutations: int = 1000, threshold: float | None = None, tail: int = 0, alpha: float = 0.05, seed=None)#

Cluster-based permutation test over the last axis (time), Maris & Oostenveld (2007).

a is (n_epochs, n_times). With b ((m_epochs, n_times)) the two conditions are compared (Welch t; epochs shuffled between conditions); without it, a is tested against zero (one-sample t; epochs sign-flipped).

Shuffling assumes the epochs are exchangeable under the null. Two conditions with clearly different variances AND different numbers of epochs break that, and the false-positive rate rises (about 10% at nominal 5% for SDs 3:1 and n 10:40) – the Welch t only shapes the clusters, it does not restore exchangeability. Inputs must be finite: a NaN would silently split a cluster.

threshold is the t value a bin must pass to join a cluster, default the two-sided alpha critical value. tail: 0 both signs, 1 positive, -1 negative. A cluster’s p is the share of permutations whose LARGEST cluster is at least as large, so the family-wise error over the window is controlled.

Returns (t_obs, clusters).

brainmaze_eeg.epochs.epoch_average(epochs) → Tuple[ndarray, ndarray]#

Mean over epochs (axis 0) and its standard error.

brainmaze_eeg.epochs.ersp_itc(epochs, fs: float, freqs: Sequence[float], n_cycles=7.0, baseline=None)#

Event-related spectral perturbation and inter-trial coherence.

epochs is (n_epochs, n_times). Each epoch is convolved with a unit-energy complex Morlet wavelet per frequency (n_cycles per frequency, or one value). Returns (ersp, itc), both (n_freqs, n_times):

  • ersp – mean power in dB relative to the mean over baseline (a boolean mask over time bins), or in dB of absolute power without one;

  • itc – |mean(exp(i * phase))| over epochs, near 0 (random phase) to 1 (locked). It is biased upward for few epochs: with random phase its expected value is about 0.89 / sqrt(n_epochs) (0.27 at 10 epochs) – judge it with itc_p_value(), not against 0.

The wavelet is longer than the epoch at low frequencies; those edge bins are NaN rather than estimated from zero padding.

brainmaze_eeg.epochs.extract_epochs(x, fs: float, events_s: Sequence[float], pre_s: float, post_s: float)#

Windows [t - pre_s, t + post_s) of x ((..., n_samples)) around each event.

events_s are seconds from the first sample. Returns (epochs, times, kept): epochs is (n_kept, ..., n_window), times the window’s time axis in seconds relative to the event, and kept a boolean mask over events_s.

brainmaze_eeg.epochs.itc_p_value(itc, n_epochs: int) → ndarray#

Rayleigh test of inter-trial coherence: the probability of an ITC at least this large from n_epochs epochs of random phase (Zar, Biostatistical Analysis, 1999, eq. 27.4).