spectral_connectivity.wrapper.multitaper_connectivity#

multitaper_connectivity(time_series: ndarray[tuple[int, ...], dtype[floating]], sampling_frequency: float, time_window_duration: float | None = None, method: str | list[str] | None = None, signal_names: Sequence[str] | None = None, squeeze: bool = False, connectivity_kwargs: dict[str, Any] | None = None, **kwargs: Any) → DataArray | Dataset[source]#

Compute connectivity measures with multitaper spectral estimation.

This is the main high-level function for connectivity analysis. It performs multitaper spectral analysis on the input time series and computes the requested connectivity measures, returning results as labeled xarray objects.

Parameters:

  • time_series (NDArray[floating],) – shape (n_times, n_trials, n_channels) or (n_times, n_channels) Time series data. For multiple trials, trials are averaged in spectral domain.

  • sampling_frequency (float) – Sampling rate in Hz of the time series data.

  • time_window_duration (float, optional) – Duration of sliding window in seconds for time-resolved analysis. If None, analyzes entire time series (no time resolution).

  • method (str or list of str, optional) – Connectivity method(s) to compute. If None, computes all available methods. Examples: “coherence_magnitude”, “imaginary_coherence”, “phase_locking_value”.

  • signal_names (sequence of str, optional) – Names for signal channels used to label dimensions. If None, uses indices.

  • squeeze (bool, default=False) – If True and n_channels=2, return connectivity between first and last channel only for symmetric measures.

  • connectivity_kwargs (dict, optional) – Additional keyword arguments passed to connectivity methods.

  • **kwargs (dict) – Additional arguments passed to Multitaper constructor (e.g., time_bandwidth_product, n_tapers, n_fft_samples).

Returns:

result –

  • DataArray if single method requested: connectivity values with dimensions [‘time’, ‘frequency’, ‘source’, ‘target’] or [‘time’, ‘frequency’] if squeezed

  • Dataset if multiple methods: collection of DataArrays, one per method

Return type:

xarray.DataArray or xarray.Dataset

Examples

>>> import numpy as np
>>> # Generate coupled oscillator data
>>> t = np.arange(0, 1, 1/500)  # 500 Hz, 1 second
>>> sig1 = np.sin(2*np.pi*10*t) + 0.1*np.random.randn(len(t))
>>> sig2 = np.sin(2*np.pi*10*t + np.pi/4) + 0.1*np.random.randn(len(t))
>>> data = np.column_stack([sig1, sig2])  # Shape: (500, 2)
>>>
>>> # Compute coherence
>>> coherence = multitaper_connectivity(
...     data, sampling_frequency=500,
...     method="coherence_magnitude",
...     signal_names=["Signal_1", "Signal_2"]
... )
>>> coherence.dims
('time', 'frequency', 'source', 'target')

>>> # Compute multiple measures
>>> measures = multitaper_connectivity(
...     data, sampling_frequency=500,
...     method=["coherence_magnitude", "imaginary_coherence"]
... )
>>> list(measures.data_vars)
['coherence_magnitude', 'imaginary_coherence']

Notes

Uses multitaper spectral estimation for robust power spectral density estimation before computing connectivity measures. This provides better spectral estimates than single-taper methods, especially for short time series.

References

[1]

Thomson, D. J. (1982). Spectrum estimation and harmonic analysis. Proceedings of the IEEE, 70(9), 1055-1096.

[2]

Percival, D. B., & Walden, A. T. (1993). Spectral Analysis for Physical Applications: Multitaper and Conventional Univariate Techniques.