gastropy.egg_process_multichannel

gastropy.egg_process_multichannel#

gastropy.egg_process_multichannel(data, sfreq, method='per_channel', filter_method='fir', band=None, **kwargs)[source]#

Process a multi-channel EGG recording.

Applies one of three named strategies to (n_channels, n_samples) EGG data:

  • "per_channel" — runs egg_process() independently on each channel. Returns metrics for all channels and identifies the channel with the strongest normogastric signal.

  • "best_channel" — uses select_best_channel() to choose the channel with the highest gastric-band peak power, then runs egg_process() on that channel only.

  • "ica" — denoises all channels via ica_denoise() (FastICA spatial decomposition) then runs "per_channel" on the reconstructed data.

Parameters:

  • data (array_like) – Multi-channel EGG data, shape (n_channels, n_samples). Must have at least 2 channels; pass a 2D array even for a single channel (shape (1, n_samples)).

  • sfreq (float) – Sampling frequency in Hz.

  • method (str, optional) – Processing strategy: "per_channel" (default), "best_channel", or "ica".

  • filter_method (str, optional) – Filter method passed to egg_process() for each channel: "fir" (default), "iir", or "dalmaijer2025". Kept separate from method (the multichannel strategy) to avoid a parameter name collision.

  • band (GastricBand, optional) – Target gastric band. Default is NORMOGASTRIA.

  • **kwargs – Additional keyword arguments passed to egg_process(). For "ica", also accepts ica_low_hz, ica_high_hz, ica_snr_threshold, and ica_random_state to control the ICA denoising step.

Returns:

result – For "per_channel" and "ica":

  • "channels" : dict mapping channel index (int) → (signals_df, info) tuples, one per channel.

  • "best_idx" : int — index of the channel with the highest normogastric band power.

  • "summary" : pd.DataFrame — one row per channel with columns channel, peak_freq_hz, instability_coefficient, proportion_normogastric, and band_power_mean.

  • "method" : str — the method used.

  • "ica_info" : dict — ICA metadata (only for "ica").

For "best_channel":

  • "signals" : pd.DataFrame — as returned by egg_process().

  • "info" : dict — as returned by egg_process(), with "best_channel_idx" added.

  • "method" : str — "best_channel".

Return type:

dict

Raises:

  • ValueError – If data is 1-dimensional or has fewer than 2 channels.

  • ValueError – If method is not one of the supported options.

Notes

best_idx in the "per_channel" and "ica" results is determined by band_power_mean from the post-processing output of egg_process(). The "best_channel" strategy uses select_best_channel(), which ranks by PSD peak power before processing. These two criteria may occasionally disagree on noisy data.

See also

egg_process

Single-channel EGG processing pipeline.

select_best_channel

Channel ranking by gastric-band peak power.

ica_denoise

ICA-based spatial denoising.

References

Dalmaijer, E. S. (2025). electrography v1.1.1. esdalmaijer/electrography

Examples

>>> import numpy as np
>>> import gastropy as gp
>>> rng = np.random.default_rng(0)
>>> t = np.arange(0, 300, 0.1)
>>> gastric = np.sin(2 * np.pi * 0.05 * t)
>>> data = np.stack([gastric + 0.1 * rng.standard_normal(len(t)),
...                  gastric + 0.1 * rng.standard_normal(len(t))])
>>> result = gp.egg_process_multichannel(data, sfreq=10.0)
>>> sorted(result.keys())
['best_idx', 'channels', 'method', 'summary']
Contents