spectral_connectivity.transforms.Welch#

class Welch(time_series: ndarray[tuple[int, ...], dtype[floating]], sampling_frequency: float, segment_duration: float | None = None, segment_overlap: float = 0.5, n_time_samples_per_segment: int | None = None, detrend_type: str | None = 'constant', start_time: float = 0, n_fft_samples: int | None = None, fft_workers: int | None = None)[source]#

Bases: object

Welch spectral transform using overlapping Hann-windowed segments.

Segment coefficients are represented on the taper/observation axis, so the default trials_tapers expectation averages both trials and Welch segments and returns a single spectrum centered on the analyzed record.

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; required because it labels the frequency axis and scales power.
segment_duration (float, optional) – Segment length in seconds; sets the frequency resolution (1 / segment_duration Hz). Strongly recommended – the fallback of 256 samples does not scale with the sampling rate. Give this or n_time_samples_per_segment.
segment_overlap (float, default=0.5) – Fractional overlap between successive segments, in [0, 1).
n_time_samples_per_segment (int, optional) – Segment length in samples (alternative to segment_duration).
detrend_type ({"constant", "linear"} or None, default="constant") – Detrending applied to each segment before the FFT.
start_time (float, default=0) – Time of the first sample, in seconds (scalar only).
n_fft_samples (int, optional) – FFT length. Defaults to scipy.fft.next_fast_len of the segment length, which may zero-pad (e.g. a 257-sample segment gives 264 bins); pass the segment length explicitly for an unpadded frequency grid.
fft_workers (int, optional) – Worker threads for SciPy’s CPU FFT (-1 uses all cores).

Attributes:

frequencies: Frequency of each FFT bin in Hz, in standard FFT order.
n_segments: Number of (overlapping) segments averaged by the estimate.
n_signals: Number of signals in the time series.
n_trials: Number of trials in the time series.
observations_are_independent: Whether the segments may be counted as independent observations.
time: Mean of the segment center times, in seconds.

Methods

fft()

Compute the Hann-windowed Fourier coefficients of every segment.

Methods

fft

Compute the Hann-windowed Fourier coefficients of every segment.

Attributes

`frequencies`	Frequency of each FFT bin in Hz, in standard FFT order.
`is_one_sided`
`n_segments`	Number of (overlapping) segments averaged by the estimate.
`n_signals`	Number of signals in the time series.
`n_trials`	Number of trials in the time series.
`observations_are_independent`	Whether the segments may be counted as independent observations.
`time`	Mean of the segment center times, in seconds.

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

Compute the Hann-windowed Fourier coefficients of every segment.

Returns:: fourier_coefficients – Shape (1, n_trials, n_segments, n_fft_samples, n_signals). Segments occupy the taper axis, so Connectivity’s trial/taper expectation averages over segments (and trials) into a single time bin.
Return type:: array

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

Frequency of each FFT bin in Hz, in standard FFT order.

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

property n_segments: int#: Number of (overlapping) segments averaged by the estimate.

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

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

property observations_are_independent: bool#

Whether the segments may be counted as independent observations.

Welch’s estimate averages the periodograms of overlapping Hann-windowed segments. For a Hann window the correlation between the periodograms of segments overlapping by 50% is small, so up to that overlap the average has close to the degrees of freedom of independent segments (Welch 1967; Percival & Walden 1993, sec. 6.17). Beyond 50% the additional segments are strongly correlated with their neighbors and add little independent information, so n_observations (trials x segments) overstates the effective sample size. 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.

Returns:: True when segment_overlap <= 0.5.
Return type:: bool

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

Mean of the segment center times, in seconds.

Returns:: time – Welch averages all segments into a single time bin.
Return type:: array, shape (1,)