gastropy.band_decompose

Contents

gastropy.band_decompose#

gastropy.band_decompose(data, sfreq, band, hwhm_hz=0.015, total_range=(0.01, 0.2))[source]#

Decompose a signal within a single gastric frequency band.

Finds the peak frequency in the band from the PSD, applies a narrowband FIR filter around that peak, then extracts instantaneous phase, amplitude, cycle durations, and summary statistics.

Parameters:

  • data (array_like) – 1D signal (e.g., raw or pre-cleaned EGG).

  • sfreq (float) – Sampling frequency in Hz.

  • band (GastricBand) – Frequency band to analyse.

  • hwhm_hz (float, optional) – Half-width at half-maximum for the narrowband filter (Hz). The passband will be [peak - hwhm, peak + hwhm]. Default is 0.015.

  • total_range (tuple of float, optional) – (fmin, fmax) for PSD computation and proportional power calculation. Default is (0.01, 0.2).

Returns:

result – Dictionary containing:

  • band : dict with name, f_lo, f_hi.

  • peak_freq_hz, max_power, mean_power, prop_power, mean_power_ratio : PSD-based metrics.

  • filtered : Narrowband-filtered signal (np.ndarray).

  • phase : Instantaneous phase in radians (np.ndarray).

  • amplitude : Instantaneous amplitude envelope (np.ndarray).

  • cycle_durations_s : Per-cycle durations (np.ndarray).

  • cycle_stats : dict from cycle_stats().

  • instability_coefficient : float.

  • filter : Filter metadata dict.

Return type:

dict

See also

multiband_analysis

Run decomposition across multiple bands.

gastropy.metrics.band_power

PSD band power metrics.

Examples

>>> import numpy as np
>>> from gastropy.timefreq import band_decompose
>>> from gastropy.metrics import NORMOGASTRIA
>>> sig = np.sin(2 * np.pi * 0.05 * np.arange(0, 300, 0.1))
>>> result = band_decompose(sig, sfreq=10.0, band=NORMOGASTRIA)
>>> result["peak_freq_hz"]
0.05
Contents