spectral_connectivity.transforms.suggest_parameters#

suggest_parameters(sampling_frequency: float, signal_duration: float, desired_freq_resolution: float | None = None, desired_n_tapers: int | None = None) → MultitaperParameters[source]#

Suggest appropriate multitaper parameters for your analysis.

This helper function recommends parameters based on your data characteristics and analysis goals. It helps answer the common question: “What parameters should I use for my data?”

Parameters:

sampling_frequency (float) – Sampling rate in Hz of your data.
signal_duration (float) – Total duration in seconds of your signal.
desired_freq_resolution (float, optional) – Target frequency resolution in Hz. If specified, parameters will be chosen to achieve approximately this resolution. Cannot be specified together with desired_n_tapers.
desired_n_tapers (int, optional) – Target number of tapers for variance reduction. If specified, time_halfbandwidth_product will be chosen to achieve this. Cannot be specified together with desired_freq_resolution.

Returns:

params – TypedDict containing suggested parameters with the following keys: - ‘sampling_frequency’: float - Input sampling frequency - ‘time_halfbandwidth_product’: float - Suggested NW - ‘time_window_duration’: float - Suggested window duration (seconds) - ‘n_tapers’: int - Number of tapers - ‘frequency_resolution’: float - Resulting frequency resolution (Hz) - ‘n_time_windows’: int - Approximate number of time windows - ‘nyquist_frequency’: float - Maximum frequency (Hz)

Return type:

MultitaperParameters

Raises:

ValueError – If desired frequency resolution is impossible to achieve with given signal duration.

Warns:

UserWarning – If both desired_freq_resolution and desired_n_tapers are specified. In this case, desired_freq_resolution takes precedence and desired_n_tapers is ignored.

Notes

Default behavior (no targets specified): - Uses NW=3 (balanced trade-off) - Sets window duration to capture ~5 time windows - Aims for reasonable frequency and time resolution

With desired_freq_resolution: - Calculates required window duration: T = 2*NW / Δf_target - Uses NW=3 by default unless this gives too few time windows - Ensures at least 3 time windows for temporal dynamics

With desired_n_tapers: - Calculates NW from: NW = (n_tapers + 1) / 2 - Uses reasonable window duration based on signal length

Examples

Get reasonable defaults for EEG data:

>>> params = suggest_parameters(
...     sampling_frequency=250,
...     signal_duration=60.0,
... )
>>> print(f"Suggested NW: {params['time_halfbandwidth_product']}")
>>> print(f"Window duration: {params['time_window_duration']:.2f}s")
>>> print(f"Frequency resolution: {params['frequency_resolution']:.2f} Hz")
>>> print(f"Number of tapers: {params['n_tapers']}")

Target specific frequency resolution:

>>> params = suggest_parameters(
...     sampling_frequency=1000,
...     signal_duration=10.0,
...     desired_freq_resolution=2.0,  # Want 2 Hz resolution
... )
>>> print(f"Achieved resolution: {params['frequency_resolution']:.2f} Hz")
Achieved resolution: 2.00 Hz

Target specific number of tapers:

>>> params = suggest_parameters(
...     sampling_frequency=1000,
...     signal_duration=5.0,
...     desired_n_tapers=9,  # Want strong averaging
... )
>>> print(f"Number of tapers: {params['n_tapers']}")
Number of tapers: 9