spectral_connectivity.wrapper.fourier_connectivity#

fourier_connectivity(fourier_coefficients: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy.complexfloating]] | ~xarray.core.dataarray.DataArray, frequencies: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy.floating]] | None = None, time: ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy.floating]] | None = None, method: str | list[str] | None = None, signal_names: ~collections.abc.Sequence[str | bytes | bool | int | float | ~numpy.integer | ~numpy.floating | ~numpy.bool | ~numpy.str_ | ~numpy.bytes_ | ~numpy.datetime64 | ~numpy.timedelta64] | None = None, squeeze: bool = False, connectivity_kwargs: dict[str, ~typing.Any] | None = None, is_one_sided: bool | None = None, *, group_labels: ~collections.abc.Sequence[~collections.abc.Hashable] | ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~typing.Any]] | None = None, frequency_range: tuple[float, float] | None = None, frequency_decimation: int = 1, frequency_bands: ~collections.abc.Mapping[str, tuple[float, float]] | None = None, frequency_reduction: ~typing.Literal['mean', 'integral'] = 'mean', time_dim: ~collections.abc.Hashable | None = None, trial_dim: ~collections.abc.Hashable | None = None, taper_dim: ~collections.abc.Hashable | None = None, frequency_dim: ~collections.abc.Hashable | None = None, signal_dim: ~collections.abc.Hashable | None = None, dtype: ~numpy.dtype[~typing.Any] | None | type[~typing.Any] | ~numpy._typing._dtype_like._SupportsDType[~numpy.dtype[~typing.Any]] | str | tuple[~typing.Any, int] | tuple[~typing.Any, ~typing.SupportsIndex | ~collections.abc.Sequence[~typing.SupportsIndex]] | list[~typing.Any] | ~numpy._typing._dtype_like._DTypeDict | tuple[~typing.Any, ~typing.Any] = <class 'numpy.complex128'>, minimum_phase_tolerance: float = 1e-08, minimum_phase_max_iterations: int = 500) → DataArray | Dataset[source]#

Compute labeled connectivity from externally estimated FFT coefficients.

The labeled output has one time axis, so the expectation is always "trials_tapers"; use Connectivity directly for expectations that retain trial/taper axes or average over time.

Parameters:

  • fourier_coefficients (array or xarray.DataArray) – Complex coefficients in (n_observations, n_frequencies, n_signals), (n_trials, n_tapers, n_frequencies, n_signals), or the core’s full (n_time, n_trials, n_tapers, n_frequencies, n_signals) layout. A DataArray is transposed by semantic dimension names (or the explicit *_dim arguments) and its frequency, time, and signal coordinates and attributes are preserved.

  • frequencies (array, shape (n_frequencies,), optional) – Frequency of each bin in Hz. A two-sided coordinate must be in standard FFT order; a non-negative, strictly increasing coordinate is treated as one-sided when is_one_sided is omitted. Taken from the DataArray coordinate when not given.

  • time (array, shape (n_time,), optional) – Center time of each window in seconds; defaults to window indices.

  • method (str or list of str, optional) – Measure name(s) from list_measures(). A single name returns a DataArray; a list (or None for DEFAULT_METHODS) returns a Dataset with one variable per measure.

  • signal_names (sequence, optional) – Labels for the source/target coordinates; defaults to the DataArray signal coordinate or "0", "1", ….

  • squeeze (bool, default=False) – Only honored when a single method (a string) is requested. If there are exactly 2 signals, reduce a pairwise measure to the single ordered pair (first source, last target), returning a (time, frequency) array that keeps the selected source and target as scalar coordinates. With more than 2 signals a warning is issued and the full matrix is returned; for power squeeze is a no-op. Length-one time is kept.

  • connectivity_kwargs (dict, optional) – Extra keyword arguments for the measure (a Connectivity method), e.g. pairs for subset_pairwise_spectral_granger_prediction or n_components for canonical_coherency; passed to every requested measure. Transform settings do not go here: they belong to the transform that produced fourier_coefficients.

  • is_one_sided (bool, optional) – Declare whether the coefficients cover only non-negative frequencies. When no frequency coordinate is available the sidedness cannot be inferred: pass True for one-sided input (e.g. rfft output) or False for a full FFT-order spectrum. False is honored as a declaration, so measures that require a two-sided spectrum run on the coefficients as given; they warn if the coefficients are not conjugate-symmetric, as the FFT of real-valued signals is, because mislabeled one-sided input makes those measures wrong. Leaving it unset in that case assumes two-sided, warns, and refuses those measures because the assumption cannot be checked. With a frequency coordinate it is inferred from frequencies.

  • group_labels (sequence, optional) – One label per signal naming the group it belongs to; labels are scalars such as integers or area names ("CA1"), and missing values (None, NaN) are rejected. Required by the group measures (canonical_coherence, canonical_coherency, maximized_imaginary_coherency, multivariate_interaction_measure, blockwise_spectral_granger_prediction and maximized_imaginary_coherency_components); an error is raised if no requested measure takes it (labels are passed only to the measures that do).

  • frequency_range ((float, float), optional) – Inclusive (low, high) bounds in Hz to keep before any decimation or band reduction.

  • frequency_decimation (int, default=1) – Keep every frequency_decimation-th frequency bin.

  • frequency_bands (mapping of str to (float, float), optional) – Named inclusive bands to reduce the frequency axis into; see frequency_band_reduce().

  • frequency_reduction ({"mean", "integral"}, default="mean") – Within-band reduction used with frequency_bands.

  • time_dim (hashable, optional) – DataArray dimension names for each axis role, when they cannot be inferred from common names.

  • trial_dim (hashable, optional) – DataArray dimension names for each axis role, when they cannot be inferred from common names.

  • taper_dim (hashable, optional) – DataArray dimension names for each axis role, when they cannot be inferred from common names.

  • frequency_dim (hashable, optional) – DataArray dimension names for each axis role, when they cannot be inferred from common names.

  • signal_dim (hashable, optional) – DataArray dimension names for each axis role, when they cannot be inferred from common names.

  • dtype (numpy.dtype, default=complex128) – Working precision for the connectivity computations.

  • minimum_phase_tolerance (float, default=1e-8) – Relative convergence tolerance of the Wilson factorization used by the directed measures.

  • minimum_phase_max_iterations (int, default=500) – Maximum Wilson iterations for the directed measures.

Returns:

Labeled result with time, frequency (or band), and measure-specific dimensions such as source/target; a DataArray for a single method name, otherwise a Dataset. Directed measures are oriented so sel(source=a, target=b) is the influence from a to b. One-sided coefficients support functional measures, but measures that need a full two-sided spectrum raise.

Return type:

xarray.DataArray or xarray.Dataset