spectral_connectivity.transforms.ShortTimeFourierTransform#

class ShortTimeFourierTransform(time_series: ndarray[tuple[int, ...], dtype[floating]], sampling_frequency: float, detrend_type: str | None = 'constant', time_window_duration: float | None = None, time_window_step: float | None = None, start_time: float = 0, n_fft_samples: int | None = None, n_time_samples_per_window: int | None = None, n_time_samples_per_step: int | None = None, fft_workers: int | None = None)[source]#

Bases: Multitaper

Short-time Fourier transform using an L2-normalized Hann window.

The returned coefficients follow the same five-dimensional contract as Multitaper, with a singleton taper axis. This makes the transform directly usable with Connectivity.from_transform() and spectral_connectivity.wrapper.connectivity_to_xarray().

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.
detrend_type ({"constant", "linear"} or None, default="constant") – Detrending applied to each window before the FFT.
time_window_duration (float, optional) – Window length in seconds. Give this or n_time_samples_per_window.
time_window_step (float, optional) – Step between successive windows in seconds (defaults to the window duration, i.e. no overlap).
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 window length, which may zero-pad (e.g. a 257-sample window gives 264 bins); pass the window length explicitly for an unpadded frequency grid.
n_time_samples_per_window (int, optional) – Window length in samples (alternative to time_window_duration).
n_time_samples_per_step (int, optional) – Step between windows in samples (alternative to time_window_step).
fft_workers (int, optional) – Worker threads for SciPy’s CPU FFT (-1 uses all cores).

Attributes:

frequencies: Return frequency of each frequency bin.
frequency_resolution: Equivalent-noise bandwidth of the periodic Hann window in Hz.
n_fft_samples: Return number of frequency bins.
n_signals: Return number of signals computed.
n_tapers: Return number of desired tapers.
n_time_samples_per_step: Return number of samples to step between windows.
n_time_samples_per_window: Return number of samples per time bin.
n_trials: Return number of trials computed.
nyquist_frequency: Return maximum resolvable frequency.
observations_are_independent: Whether the trial/taper observations may be counted as independent.
start_time: Independent read-only copy of the transform’s start-time coordinate.
taper_eigenvalues: DPSS spectral-concentration ratios used for taper weighting.
tapers: Return the tapers used for the multitaper function.
time: Return time of each time bin.
time_bins_are_independent: Whether the time windows may be counted as independent observations.
time_series: Independent read-only copy of the input time-series snapshot.
time_window_duration: Return duration of each time bin.
time_window_step: Return how much each time window slides.

Methods

`fft`()	Compute the fast Fourier transform using the multitaper method.
`summarize_parameters`()	Generate a human-readable summary of the multitaper analysis parameters.

Methods

`fft`	Compute the fast Fourier transform using the multitaper method.
`summarize_parameters`	Generate a human-readable summary of the multitaper analysis parameters.

Attributes

`frequencies`	Return frequency of each frequency bin.
`frequency_resolution`	Equivalent-noise bandwidth of the periodic Hann window in Hz.
`is_one_sided`	Multitaper returns the full two-sided FFT spectrum (both positive and negative frequencies), so consumers must not assume a one-sided layout.
`n_fft_samples`	Return number of frequency bins.
`n_signals`	Return number of signals computed.
`n_tapers`	Return number of desired tapers.
`n_time_samples_per_step`	Return number of samples to step between windows.
`n_time_samples_per_window`	Return number of samples per time bin.
`n_trials`	Return number of trials computed.
`nyquist_frequency`	Return maximum resolvable frequency.
`observations_are_independent`	Whether the trial/taper observations may be counted as independent.
`start_time`	Independent read-only copy of the transform's start-time coordinate.
`taper_eigenvalues`	DPSS spectral-concentration ratios used for taper weighting.
`tapers`	Return the tapers used for the multitaper function.
`time`	Return time of each time bin.
`time_bins_are_independent`	Whether the time windows may be counted as independent observations.
`time_series`	Independent read-only copy of the input time-series snapshot.
`time_window_duration`	Return duration of each time bin.
`time_window_step`	Return how much each time window slides.

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

Compute the fast Fourier transform using the multitaper method.

Returns:: fourier_coefficients – Shape (n_time_windows, n_trials, n_tapers, n_fft_samples, n_signals). Complex-valued Fourier coefficients.
Return type:: array

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

Return frequency of each frequency bin.

Returns:: Frequency values in Hz corresponding to FFT bins.
Return type:: NDArray[float64], shape (n_frequencies,)

property frequency_resolution: float#: Equivalent-noise bandwidth of the periodic Hann window in Hz.

is_one_sided = False#: Multitaper returns the full two-sided FFT spectrum (both positive and negative frequencies), so consumers must not assume a one-sided layout.

property n_fft_samples: int#

Return number of frequency bins.

Returns:: Number of FFT samples.
Return type:: int

property n_signals: int#

Return number of signals computed.

Returns:: Number of signals in the time series.
Return type:: int

property n_tapers: int#

Return number of desired tapers.

Note that the number of tapers may be less than this number if the bias of the tapers is too high (eigenvalues > MIN_EIGENVALUE_THRESHOLD = 0.9).

Returns:: Number of tapers to use.
Return type:: int

property n_time_samples_per_step: int#

Return number of samples to step between windows.

An explicit n_time_samples_per_step is used as given. Otherwise, if time_window_step is set, the step is the nearest whole number of samples in that duration. If neither is set, the step defaults to the window length (non-overlapping windows).

Returns:: Number of samples to advance between windows.
Return type:: int

property n_time_samples_per_window: int#

Return number of samples per time bin.

Returns:: Number of time samples in each window.
Return type:: int
Raises:: ValueError – If neither n_time_samples_per_window nor time_window_duration is set.

property n_trials: int#

Return number of trials computed.

Returns:: Number of trials in the time series.
Return type:: int

property nyquist_frequency: float#

Return maximum resolvable frequency.

Returns:: Nyquist frequency in Hz.
Return type:: float

property observations_are_independent: bool#

Whether the trial/taper observations may be counted as independent.

DPSS tapers are orthogonal, so for a process that is smooth across the taper bandwidth the eigencoefficients of one window are approximately uncorrelated (Thomson 1982; Percival & Walden 1993, ch. 7), and trials are independent realizations. Connectivity reads this flag to decide whether n_observations (trials x tapers) counts effectively independent samples: the jackknife, the debiased measures (pairwise phase consistency, debiased squared PLI/WPLI) and the zero-coherence significance test (Beta(1, n_observations - 1) null) all assume it does. Always True for this transform. The flag describes the observations within one window; correlation between overlapping windows, which matters only for expectations that also average over time, is reported by time_bins_are_independent.

Return type:: bool

property start_time: Any#: Independent read-only copy of the transform’s start-time coordinate.

summarize_parameters() → str#

Generate a human-readable summary of the multitaper analysis parameters.

This method displays key parameters and their implications for your analysis, making it easier to understand and communicate your spectral analysis settings.

Returns:: summary – A formatted string containing: - Input parameters (sampling frequency, time-halfbandwidth product) - Derived parameters (n_tapers, frequency resolution) - Data dimensions (n_signals, n_trials, n_time_samples) - Frequency range (0 to Nyquist)
Return type:: str

Examples

>>> import numpy as np
>>> from spectral_connectivity.transforms import Multitaper
>>> data = np.random.default_rng(0).standard_normal((5000, 1, 64))  # 5s, 64 EEG channels
>>> mt = Multitaper(
...     data,
...     sampling_frequency=1000,
...     time_window_duration=1.0,
...     time_halfbandwidth_product=3,
... )
>>> print(mt.summarize_parameters())
Multitaper Spectral Analysis Configuration
===========================================

Data Shape
----------
Time samples:    5000 (5.00 seconds)
Signals:         64
Trials:          1

Spectral Parameters
-------------------
Sampling frequency:            1000 Hz
Time-halfbandwidth product:    3
Number of tapers:              5

Time Windowing
--------------
Window duration:  1.000 s (1000 samples)
Window step:      1.000 s (non-overlapping)
Number of windows: 5

Frequency Analysis
------------------
Frequency resolution: 6.0 Hz
Nyquist frequency:    500.0 Hz
Frequency range:      0.0 - 500.0 Hz
FFT samples:          1000

See also

suggest_parameters: Get parameter suggestions before creating Multitaper
estimate_frequency_resolution: Estimate frequency resolution
estimate_n_tapers: Estimate number of tapers

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

DPSS spectral-concentration ratios used for taper weighting.

Returns None for custom tapers, whose concentration ratios are not known. The returned array is a detached read-only copy.

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

Return the tapers used for the multitaper function.

Tapers are the windowing function.

Returns:: tapers – The tapers used for windowing.
Return type:: array_like, shape (n_time_samples_per_window, n_tapers)

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

Return time of each time bin.

Returns:: Time values in seconds for center of each time window.
Return type:: NDArray[float64], shape (n_time_windows,)

property time_bins_are_independent: bool#

Whether the time windows may be counted as independent observations.

An expectation that averages over time ("time", "time_tapers", …) counts every window in n_observations. Windows that share samples are correlated, so beyond some overlap that count overstates the effective sample size and biases the measures that rely on it (pairwise phase consistency of independent signals, for example, is no longer centered on 0). Like Welch, which treats segments overlapping by at most 50% as approximately independent (Welch 1967; Percival & Walden 1993, sec. 6.17), windows count as independent when n_time_samples_per_step is at least half of n_time_samples_per_window. Connectivity warns when an expectation averages over correlated time bins.

Returns:: True when successive windows overlap by at most half.
Return type:: bool

property time_series: Any#: Independent read-only copy of the input time-series snapshot.

property time_window_duration: float#

Return duration of each time bin.

Returns:: Duration in seconds of each time window actually analyzed, n_time_samples_per_window / sampling_frequency (a requested duration is rounded to the nearest sample).
Return type:: float

property time_window_step: float#

Return how much each time window slides.

Returns:: Step size in seconds between consecutive time windows actually taken, n_time_samples_per_step / sampling_frequency (a requested step is rounded to the nearest sample).
Return type:: float