spectral_connectivity.wrapper.frequency_band_reduce#

frequency_band_reduce(result: DataArray | Dataset, bands: Mapping[str, tuple[float, float]], *, reduction: Literal['mean', 'integral'] = 'mean', circular: bool | None = None) → DataArray | Dataset[source]#

Reduce a frequency-resolved result into labeled frequency bands.

reduction="mean" averages the already-computed connectivity score over the bins in each inclusive band. Phase is treated specially: a coherence_phase result uses a circular mean, while complex-valued measures use their ordinary complex (vector) mean. reduction="integral" integrates a spectral density over [low, high] and is intentionally restricted to power and cross_spectral_density, where it represents band power/covariance rather than a frequency-averaged score. Each bin stands for the frequency cell between the midpoints to its neighbours, and contributes its density times the part of that cell inside the band, so band edges need not fall on bins, a one-bin band is not zero, and adjacent bands add up to their union. On a one-sided grid starting at 0 Hz the DC bin and the Nyquist bin (present for an even FFT length) own only the half-cell toward their neighbour but count with a full spacing, matching the one-sided convention in which those two bins are not doubled; integrating power over a band that covers every bin therefore reproduces the total signal power (Parseval).

Parameters:

  • result (xarray.DataArray or xarray.Dataset) – Result with a one-dimensional frequency coordinate.

  • bands (mapping of str to (float, float)) – Inclusive lower and upper frequency bounds in the coordinate’s units.

  • reduction ({"mean", "integral"}, default="mean") – Scientifically defined reduction to apply within each band.

  • circular (bool, optional) – Use a circular mean (for phase angles in radians). By default it is inferred per variable: coherence_phase results and variables with units="rad" are averaged circularly. Pass True/False to override, e.g. for a phase array whose name and attrs were removed.

Returns:

Same type as result with the frequency dimension replaced by a band dimension holding the band names, and the band definitions recorded in attrs["frequency_bands_json"]. An integral is in the density’s units without the /Hz (e.g. (uV)^2/Hz becomes (uV)^2) and is labeled "Band power" or "Band cross-power".

Return type:

xarray.DataArray or xarray.Dataset

Notes

Spatial filters, spatial patterns, and global-coherence vectors have an arbitrary sign or complex phase independently at each frequency. A Dataset containing those variables is therefore rejected instead of averaging them into a scientifically undefined band projection. Select the scalar score variable from the Dataset and reduce that DataArray when only band scores are needed.

A band is undefined wherever any of its bins is NaN (for example an edge-invalid MorletWavelet bin under edge_mode="nan"): both reductions return NaN there rather than silently reducing the valid bins only. When the input carries a valid_time_frequency coordinate the result gains a valid_time_band coordinate that is True only where every bin of the band had full support.

The Nyquist frequency is half the sampling rate recorded in result’s provenance attrs (e.g. mt_sampling_frequency). If none is recorded, the last bin of a grid starting at 0 Hz is taken to be the Nyquist bin, so reduce such a result before cropping it.