gastropy.detect_phase_artifacts

gastropy.detect_phase_artifacts#

gastropy.detect_phase_artifacts(phase, times, sd_threshold=3.0)[source]#

Detect artifact cycles in an EGG phase time series.

Uses two phase-based criteria from Wolpert et al. (2020):

  1. Non-monotonic phase: cycles where the phase does not increase monotonically from -pi to +pi.

  2. Duration outliers: cycles whose duration falls outside mean +/- sd_threshold standard deviations.

Parameters:

  • phase (array_like) – Instantaneous phase in radians (-pi to pi), typically from instantaneous_phase applied to a bandpass-filtered signal.

  • times (array_like) – Time values in seconds corresponding to each phase sample.

  • sd_threshold (float, optional) – Number of standard deviations for the duration outlier criterion. Default is 3.0.

Returns:

Dictionary with keys:

  • artifact_mask : ndarray of bool, shape (n_samples,) True for samples belonging to an artifact cycle.

  • artifact_segments : list of (start_idx, end_idx) tuples Index ranges of each artifact cycle.

  • cycle_edges : ndarray of int Sample indices of cycle boundaries.

  • cycle_durations_s : ndarray of float Duration of each cycle in seconds.

  • n_artifacts : int Total number of artifact cycles detected.

  • duration_outlier_cycles : ndarray of int Indices of cycles flagged as duration outliers.

  • nonmonotonic_cycles : ndarray of int Indices of cycles flagged as non-monotonic.

Return type:

dict

References

Wolpert, N., Rebollo, I., & Tallon-Baudry, C. (2020). Electrogastrography for psychophysiological research: Practical considerations, analysis pipeline, and normative data in a large sample. Psychophysiology, 57, e13599.

Examples

>>> import numpy as np
>>> from gastropy.signal import instantaneous_phase, apply_bandpass
>>> from gastropy.signal import detect_phase_artifacts
>>> t = np.arange(0, 300, 0.1)
>>> sig = np.sin(2 * np.pi * 0.05 * t)
>>> filtered, _ = apply_bandpass(sig, sfreq=10.0, low_hz=0.03, high_hz=0.07)
>>> phase, _ = instantaneous_phase(filtered)
>>> artifacts = detect_phase_artifacts(phase, t)
>>> artifacts["n_artifacts"]
0
Contents