spectral_connectivity.transforms.MorletWavelet#

class MorletWavelet(time_series: ndarray[tuple[int, ...], dtype[floating]], sampling_frequency: float, frequencies: ndarray[tuple[int, ...], dtype[floating]], n_cycles: float | ndarray[tuple[int, ...], dtype[floating]] = 7.0, *, decimation: int = 1, smoothing_time: float | None = None, smoothing_step: float | None = None, smoothing_frequency: int = 1, smoothing_kernel: Literal['boxcar', 'hann'] = 'boxcar', padding_mode: Literal['constant', 'reflect', 'edge'] = 'constant', edge_mode: Literal['keep', 'nan', 'trim'] = 'keep', zero_mean: bool = True, start_time: float = 0.0)[source]#

Bases: object

Complex Morlet transform with explicit edge and 2-D smoothing controls.

Coefficients contain only the requested positive frequencies and therefore support functional, but not Wilson-factorized directed, connectivity. With multiple trials, the default expectation averages trials at each time point. For a single continuous trial, set smoothing_time to collect neighboring wavelet coefficients on the observation axis; otherwise normalized pairwise measures are degenerate at unit magnitude.

Parameters:

time_series (ndarray, shape (n_time_samples, n_trials, n_signals)) – Input signals. Use prepare_time_series() for 1-D/2-D input.
sampling_frequency (float) – Samples per second (Hz).
frequencies (ndarray, shape (n_frequencies,)) – Strictly increasing positive frequencies (Hz) below Nyquist.
n_cycles (float or ndarray, default=7.0) – Number of oscillation cycles per wavelet, scalar or one per frequency. Controls the time/frequency-resolution trade-off: more cycles give sharper frequency but coarser time resolution.
decimation (int, default=1) – Keep every decimation-th output sample to reduce memory/compute.
smoothing_time (float, optional) – Duration (seconds) of a sliding window whose coefficients are collected onto the observation axis. Set this for single-trial data so normalized measures (coherence, PLV) are not degenerate. Coefficients closer than a few wavelet standard deviations sigma_t = n_cycles / (2 pi f) are strongly autocorrelated, so the window must span several sigma_t to hold more than one effectively independent sample: use at least 4 * n_cycles / (2 * pi * f_min) seconds (0.45 s for 7 cycles at 10 Hz), and expect the effective sample count to stay well below the number of coefficients in the window. For a single trial a shorter window emits a UserWarning, because it biases normalized measures of independent signals toward 1; with multiple trials the trial/taper expectation also averages independent realizations, so no warning is emitted.
smoothing_step (float, optional) – Step (seconds) between smoothing windows; defaults to smoothing_time and requires it.
smoothing_frequency (int, default=1) – Odd number of adjacent requested frequency bins collected into each local estimate. Frequency boundaries are reflected, matching the boundary convention used by MNE’s time-resolved spectral smoothing.
smoothing_kernel ({"boxcar", "hann"}, default="boxcar") – Separable time/frequency weights for the local estimate. "boxcar" preserves the historical equal-weight smoothing; "hann" reduces discontinuities at the neighborhood boundary. The Hann weights are the interior of a symmetric Hann window two samples wider than the neighborhood, so every sample carries a non-zero weight (e.g. smoothing_frequency=3 weights the bins [0.5, 1, 0.5]).
padding_mode ({"constant", "reflect", "edge"}, default="constant") – How the time series is extended before convolution. "constant" (zero padding) preserves the historical transform.
edge_mode ({"keep", "nan", "trim"}, default="keep") – Treatment of coefficients whose five-standard-deviation wavelet support extends beyond the original record. "keep" retains padded values, "nan" makes derived estimates NaN, and "trim" removes times that are not valid for every requested frequency.
zero_mean (bool, default=True) – Subtract the wavelet’s mean so it has no DC response.
start_time (float, default=0.0) – Time of the first sample, in seconds.

Attributes:

edge_half_width: Wavelet half-support at each frequency, in seconds.
frequencies: Wavelet center frequencies in Hz.
n_cycles: Number of wavelet cycles at each frequency, shape (n_frequencies,).
n_signals: Number of signals in the time series.
n_trials: Number of trials in the time series.
observation_weights: Weights consumed by Connectivity for local expectations.
observations_are_independent: Whether the observation axis holds independent samples.
time: Center time of each output time bin, in seconds.
time_bins_are_independent: Whether the output time bins may be counted as independent observations.
valid_time_frequency: Mask where the full wavelet and smoothing support is in-record.

Methods

fft()

Compute one-sided Morlet coefficients grouped by smoothing neighborhood.

Methods

fft

Compute one-sided Morlet coefficients grouped by smoothing neighborhood.

Attributes

`edge_half_width`	Wavelet half-support at each frequency, in seconds.
`frequencies`	Wavelet center frequencies in Hz.
`is_one_sided`
`n_cycles`	Number of wavelet cycles at each frequency, shape (n_frequencies,).
`n_signals`	Number of signals in the time series.
`n_trials`	Number of trials in the time series.
`observation_weights`	Weights consumed by `Connectivity` for local expectations.
`observations_are_independent`	Whether the observation axis holds independent samples.
`time`	Center time of each output time bin, in seconds.
`time_bins_are_independent`	Whether the output time bins may be counted as independent observations.
`valid_time_frequency`	Mask where the full wavelet and smoothing support is in-record.

property edge_half_width: ndarray[tuple[int, ...], dtype[floating]]#: Wavelet half-support at each frequency, in seconds.

fft() → ndarray[tuple[int, ...], dtype[complexfloating]][source]#

Compute one-sided Morlet coefficients grouped by smoothing neighborhood.

Returns:: fourier_coefficients – Shape (n_time, n_trials, n_smoothing_time * n_smoothing_frequency, n_frequencies, n_signals). The neighboring time samples and frequencies of each smoothing window occupy the taper axis, so Connectivity’s trial/taper expectation (weighted by observation_weights) forms the local smoothed estimate. |coefficient|**2 is a one-sided power spectral density.
Return type:: array

property frequencies: ndarray[tuple[int, ...], dtype[floating]]#

Wavelet center frequencies in Hz.

Returns:: frequencies
Return type:: array, shape (n_frequencies,)

property n_cycles: ndarray[tuple[int, ...], dtype[floating]]#: Number of wavelet cycles at each frequency, shape (n_frequencies,).

property n_signals: int#: Number of signals in the time series.

property n_trials: int#: Number of trials in the time series.

property observation_weights: ndarray[tuple[int, ...], dtype[floating]] | None#

Weights consumed by Connectivity for local expectations.

Returns:: observation_weights – Shape (n_time, n_trials, n_smoothing_time * n_smoothing_frequency, n_frequencies, 1). None when every observation has equal weight (a uniform smoothing kernel without edge_mode="nan" masking), so Connectivity uses its plain, unweighted expectation.
Return type:: array or None

property observations_are_independent: bool#

Whether the observation axis holds independent samples.

Without smoothing the observation axis holds one coefficient per trial, and trials are independent realizations. With smoothing_time or smoothing_frequency the axis also holds neighboring coefficients of the same trial, which are strongly autocorrelated: the wavelet’s Gaussian envelope (temporal standard deviation n_cycles / (2 pi f)) correlates coefficients closer than a few standard deviations, and adjacent frequency bins overlap in bandwidth. n_observations then overstates the effective sample size, and normalized measures of independent signals are biased toward 1. Connectivity reads this flag before the jackknife, the debiased measures (pairwise phase consistency, debiased squared PLI/WPLI) and the zero-coherence significance test, whose finite-sample corrections assume independent observations. Correlation between successive time bins, which matters only for expectations that also average over time, is reported by time_bins_are_independent.

Returns:: True only when the smoothing neighborhood is a single sample (no smoothing, or a one-sample window that merely decimates).
Return type:: bool

property time: ndarray[tuple[int, ...], dtype[floating]]#

Center time of each output time bin, in seconds.

Returns:: time – Decimated sample times, averaged over each smoothing window when time smoothing is enabled.
Return type:: array, shape (n_time,)

property time_bins_are_independent: bool#

Whether the output time bins may be counted as independent observations.

An expectation that averages over time ("time_trials", …) counts every time bin in n_observations. Wavelet coefficients closer than a few envelope standard deviations sigma_t = n_cycles / (2 pi f) are strongly autocorrelated (coefficient autocorrelation ~ exp(-dt^2 / (4 sigma_t^2))), so without decimation adjacent samples are nearly duplicates and that count overstates the effective sample size. Bins count as independent when the closest coefficients of successive bins are at least 4 * sigma_t apart at the widest wavelet, the spacing the smoothing_time guidance also uses. Connectivity warns when an expectation averages over correlated time bins.

Returns:: True when decimation and the smoothing step leave at least 4 * n_cycles / (2 pi f_min) seconds between successive bins.
Return type:: bool

property valid_time_frequency: ndarray[tuple[int, ...], dtype[bool]]#: Mask where the full wavelet and smoothing support is in-record.