gastropy.neuro.fmri.bold_voxelwise_phases

gastropy.neuro.fmri.bold_voxelwise_phases#

gastropy.neuro.fmri.bold_voxelwise_phases(bold_2d, peak_freq_hz, sfreq, hwhm_hz=0.015, begin_cut=0, end_cut=0, filter_method='iir', filter_order=4)[source]#

Extract instantaneous phase at the gastric frequency for each voxel.

Bandpass-filters each voxel’s BOLD time series at the individual gastric peak frequency, then applies the Hilbert transform to extract the instantaneous phase. Optionally trims edge volumes to remove filter ringing artifacts.

The default IIR (Butterworth) filter is used because FIR filters require many more taps than available BOLD volumes at typical fMRI sampling rates (~0.5 Hz). IIR filtering is vectorized across all voxels for performance.

Parameters:

  • bold_2d (array_like, shape (n_voxels, n_timepoints)) – BOLD time series (typically confound-regressed residuals).

  • peak_freq_hz (float) – Individual gastric peak frequency in Hz (e.g., 0.05 for 3 cpm).

  • sfreq (float) – BOLD sampling frequency in Hz (1 / TR).

  • hwhm_hz (float, optional) – Half-width at half-maximum of the bandpass filter in Hz. Default is 0.015 Hz, matching the StomachBrain pipeline.

  • begin_cut (int, optional) – Number of timepoints to remove from the start. Default is 0.

  • end_cut (int, optional) – Number of timepoints to remove from the end. Default is 0.

  • filter_method (str, optional) – "iir" (default) for Butterworth, "fir" for FIR. IIR is recommended for BOLD data where the number of volumes is typically too short for high-order FIR filters.

  • filter_order (int, optional) – Butterworth filter order when filter_method="iir". Default is 4.

Returns:

phases – Instantaneous phase in radians (-pi to pi) for each voxel.

Return type:

np.ndarray, shape (n_voxels, n_timepoints_trimmed)

Contents