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).
ais(n_epochs, n_times). Withb((m_epochs, n_times)) the two conditions are compared (Welch t; epochs shuffled between conditions); without it,ais 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.
thresholdis the t value a bin must pass to join a cluster, default the two-sidedalphacritical 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.
epochsis(n_epochs, n_times). Each epoch is convolved with a unit-energy complex Morlet wavelet per frequency (n_cyclesper frequency, or one value). Returns(ersp, itc), both(n_freqs, n_times):ersp– mean power in dB relative to the mean overbaseline(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 about0.89 / sqrt(n_epochs)(0.27 at 10 epochs) – judge it withitc_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)ofx((..., n_samples)) around each event.events_sare seconds from the first sample. Returns(epochs, times, kept):epochsis(n_kept, ..., n_window),timesthe window’s time axis in seconds relative to the event, andkepta boolean mask overevents_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_epochsepochs of random phase (Zar, Biostatistical Analysis, 1999, eq. 27.4).