API Reference

GastroPy exposes a flat namespace: most functions are accessible directly from import gastropy as gp. The reference below is organized by submodule.

EGG — Core Pipeline

High-level functions for EGG signal processing.

egg_process	Process an EGG signal through the full analysis pipeline.
egg_clean	Clean an EGG signal by applying a bandpass filter.
egg_process_multichannel	Process a multi-channel EGG recording.
select_best_channel	Select the EGG channel with the strongest gastric rhythm.
select_peak_frequency	Find the peak frequency in the gastric band from a single channel.

Signal — DSP Utilities

Low-level signal processing building blocks.

psd_welch	Compute power spectral density using Welch's method.
design_fir_bandpass	Design a FIR bandpass filter with adaptive tap count.
apply_bandpass	Apply a zero-phase bandpass filter to a signal.
instantaneous_phase	Compute instantaneous phase via the Hilbert transform.
cycle_durations	Detect complete cycles from phase and return their durations.
mean_phase_per_window	Compute mean phase angle within each time window.
resample_signal	Resample a signal to a new sampling frequency.
detect_phase_artifacts	Detect artifact cycles in an EGG phase time series.
find_cycle_edges	Detect cycle boundaries from a wrapped phase time series.

Signal — Preprocessing & Artifact Removal

Time-domain preprocessing functions for artifact removal before bandpass filtering. All accept 1D or 2D (n_channels, n_samples) arrays.

hampel_filter	Remove spike artifacts using the Hampel median identifier.
mad_filter	Remove outliers using a global median absolute deviation filter.
remove_movement_artifacts	Attenuate movement artifacts using an LMMSE Wiener filter.
ica_denoise	Denoise multi-channel EGG using Independent Component Analysis.
fit_sine	Fit a sine wave to an EGG signal using least-squares optimisation.
sine_model	Evaluate a sine wave.

Metrics — Rhythm Quantification

Gastric rhythm metrics and quality assessment.

band_power	Compute power metrics for a specific frequency band.
instability_coefficient	Compute the instability coefficient (IC) of gastric rhythm.
cycle_stats	Compute summary statistics for cycle durations.
proportion_normogastric	Compute the proportion of cycles in the normogastric range.
assess_quality	Assess EGG recording quality based on standard criteria.
GastricBand	A named gastric frequency band.
NORMOGASTRIA	A named gastric frequency band.
BRADYGASTRIA	A named gastric frequency band.
TACHYGASTRIA	A named gastric frequency band.
GASTRIC_BANDS	Built-in mutable sequence.

Time-Frequency — Per-Band Decomposition

Decompose signals across gastric frequency bands.

band_decompose	Decompose a signal within a single gastric frequency band.
multiband_analysis	Run per-band decomposition across multiple gastric frequency bands.
morlet_tfr	Compute time-frequency power using Morlet wavelet convolution.

Coupling — Phase Coupling Analysis

Phase-locking value (PLV), surrogate testing, and circular statistics for gastric-brain coupling analyses.

phase_locking_value	Compute the phase-locking value between two phase time series.
phase_locking_value_complex	Compute the complex phase-locking value.
surrogate_plv	Compute surrogate PLV via circular time-shifting.
coupling_zscore	Compute z-scored coupling strength (empirical vs. surrogate).
circular_mean	Compute the circular (directional) mean of phase values.
resultant_length	Compute the mean resultant length of phase values.
rayleigh_test	Rayleigh test for non-uniformity of circular data.

IO — BIDS Physio I/O

Read and write BIDS-formatted peripheral physiology recordings, and convert from common acquisition formats. For MATLAB users, see examples/matlab/egg_to_bids.m.

read_bids_physio	Read a BIDS _physio.tsv.gz and its companion JSON sidecar.
write_bids_physio	Write signal data as BIDS _physio.tsv.gz with companion JSON sidecar.
parse_bids_filename	Parse BIDS key-value entities from a filename.
brainvision_to_bids	Convert a BrainVision EGG recording to BIDS physio format.

Data — Sample Datasets

Load bundled example EGG recordings for tutorials and testing. Sample data is stored in BIDS physio format. fetch_fmri_bold downloads preprocessed fMRI data from a GitHub Release.

load_fmri_egg	Load a sample fMRI-EGG recording.
load_egg	Load a sample standalone EGG recording.
list_datasets	List available sample datasets.
fetch_fmri_bold	Download preprocessed fMRI BOLD data for coupling analysis.

Viz — Visualization

Plotting functions for EGG signals and gastric rhythm analysis.

plot_psd	Plot power spectral density with gastric band shading.
plot_egg_overview	Plot a 4-panel EGG overview: raw, filtered, phase, amplitude.
plot_cycle_histogram	Plot histogram of gastric cycle durations.
plot_artifacts	Plot phase time series with artifact regions highlighted.
plot_volume_phase	Plot per-volume mean phase from fMRI-EGG coupling.
plot_egg_comprehensive	Create a comprehensive multi-panel EGG analysis figure.
plot_tfr	Plot a time-frequency representation as a heatmap.
plot_coupling_map	Plot a volumetric coupling map as an anatomical overlay.
plot_glass_brain	Plot a coupling map as a transparent glass brain.

Neuro — Neuroimaging Utilities

Functions specific to gastric-brain coupling with fMRI, EEG, and MEG. Access via gastropy.neuro.fmri.

find_scanner_triggers	Extract fMRI scanner trigger onset times from MNE annotations.
create_volume_windows	Create volume window index pairs from trigger onsets.
phase_per_volume	Extract mean phase angle for each fMRI volume.
apply_volume_cuts	Remove transient volumes from the start and end of a time series.
regress_confounds	Remove confound signals from BOLD data via GLM regression.
bold_voxelwise_phases	Extract instantaneous phase at the gastric frequency for each voxel.
compute_plv_map	Compute a voxelwise PLV map between EGG and BOLD phases.
compute_surrogate_plv_map	Compute a surrogate PLV map via circular time-shifting.
load_bold	Load fMRIPrep BOLD and brain mask as a masked 2D array.
align_bold_to_egg	Align BOLD volumes to EGG trigger count.
to_nifti	Convert a 3D numpy array to a nibabel NIfTI image.