Warn when Epochs events fall outside the raw data range (#12989) by CedricConday · Pull Request #14004 · mne-tools/mne-python

CedricConday · 2026-06-30T03:41:25Z

What was wrong

When mne.Epochs is created from an events array containing sample numbers outside the data, the corresponding epochs are silently dropped with no indication that the events were out of bounds. This is easy to hit when events was generated at a different sampling frequency, or contains samples before first_samp.

Fix

At construction, compute each epoch's sample window (the same start/stop math used by _get_epoch_from_raw) and warn if any fall before the start or past the end of the raw data, reporting how many.

Test

Adds test_epochs_warn_out_of_bounds_events: an event past the end of the data now raises a RuntimeWarning. Verified it does not warn on main (the silent-drop behavior) and warns with this change.

AI-assisted, human-reviewed — I'm an AI engineer; I find, fix, and test with AI (Claude Code), then review and verify before opening.

tsbinns · 2026-06-30T13:21:00Z

Thanks for opening this PR @CedricConday!

I agree with the discussion in the issue that there should be an option to control whether a warning is emitted. That would also be in line with how we handle the similar situation for setting annotations in Raw objects that are outside the data boundaries:

mne-python/mne/io/base.py

Lines 714 to 719 in 90b8cee

    
               def set_annotations( 
        
                   self, annotations, emit_warning=True, on_missing="raise", *, verbose=None 
        
               ): 
        
                   """Setter for annotations. 
        
                   This setter checks if they are inside the data range.

Mirrors the on_missing pattern used for out-of-range Raw annotations (_on_missing helper): 'raise' | 'warn' (default) | 'ignore'. Addresses maintainer review on mne-toolsgh-14004.

CedricConday · 2026-06-30T14:19:42Z

Thanks @tsbinns! Added an on_outside parameter ('raise' | 'warn' | 'ignore', default 'warn') routed through the _on_missing helper, mirroring the out-of-range Raw annotations handling you linked. Updated the docstring, changelog entry, and tests (warn / raise / ignore + the in-range no-warn case). Happy to change the default or the name if you'd prefer.

tsbinns

Thanks for adding the extra control @CedricConday!
Just a few comments.

tsbinns · 2026-07-01T18:52:37Z

+        # Warn when an event's *sample number* falls outside the recorded data
+        # (before ``first_samp`` or at/after the last sample). Such an event yields
+        # no epoch and is silently dropped, which is surprising and usually means
+        # the events were created at a different sampling frequency or precede
+        # ``first_samp``. This checks the event positions, not the epoch window —
+        # an in-range event whose window merely clips the edge is normal and quiet.
+        # See gh-12989.
+        if self._raw is not None and len(self.events) > 0:
+            lo = self._raw.first_samp
+            hi = lo + self._raw.n_times
+            n_oob = int(((self.events[:, 0] < lo) | (self.events[:, 0] >= hi)).sum())
+            if n_oob:
+                _on_missing(
+                    on_outside,
+                    f"{n_oob} event{_pl(n_oob)} {'has' if n_oob == 1 else 'have'} a "
+                    "sample number outside the recorded data; the corresponding "
+                    f"epoch{_pl(n_oob)} will be dropped. This can happen if the "
+                    "events were created at a different sampling frequency, or "
+                    "contain sample numbers before first_samp.",
+                    name="on_outside",
+                )
+


I'd suggest including this within BaseEpochs, as we'd want this warning for both the Epochs and EpochsArray classes.

Also, might be worth only checking for this after selection has been applied in BaseEpochs.

tsbinns · 2026-07-01T18:55:38Z

        event_repeated="error",
+        on_outside="warn",
        verbose=None,


Suggested change

event_repeated="error",

on_outside="warn",

verbose=None,

event_repeated="error",

*,

on_outside="warn",

verbose=None,

Should make sure this new param is kwarg only.

Likewise, when the param is added to EpochsArray, it should be as kwarg-only (like some others there).

tsbinns · 2026-07-01T18:57:27Z

+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        mne.Epochs(raw, oob, tmin=-0.2, tmax=0.5, baseline=None, on_outside="ignore")
+    # an in-range event whose epoch window merely clips the edge must NOT warn
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        mne.Epochs(raw, np.array([[990, 0, 1]]), tmin=0, tmax=0.5, baseline=None)


Warnings count as errors in our tests, so we don't need to catch them.

tsbinns · 2026-07-01T19:01:50Z

@CedricConday Please also link your GitHub account to CircleCI so that the documentation build will run, and we can verify that looks good.

Events whose epoch window lies (partly) outside the raw data are silently dropped, which is surprising e.g. when events come from a different sampling frequency or contain samples before first_samp. Warn at construction listing how many events are out of bounds. Adds a regression test.

Warn only when an event's sample number falls outside the recorded data ([first_samp, first_samp + n_times)) — the issue's actual scenario (events at a different sampling frequency, or before first_samp). The earlier check on the epoch *window* also fired for in-range events whose window merely clips the edge (wide tmax / negative tmin on short data), which is normal and broke several existing tests. Full test_epochs.py is green under -W error.

for more information, see https://pre-commit.ci

Mirrors the on_missing pattern used for out-of-range Raw annotations (_on_missing helper): 'raise' | 'warn' (default) | 'ignore'. Addresses maintainer review on mne-toolsgh-14004.

…x test - on_outside made keyword-only in both Epochs and EpochsArray - Warning logic moved from Epochs to BaseEpochs._oob_check for reuse - EpochsArray now accepts and forwards on_outside to BaseEpochs - Test uses pytest.raises instead of pytest.warns per mne warnings-as-errors policy

…-as-errors, add missing BaseEpochs on_outside doc

…event file (mne-toolsgh-12989) test_warnings and test_n_components_none pass the complete event file against a shorter/cropped raw, so some events fall past the data and are dropped — expected here. Pass on_outside='ignore' at those call sites so the new default warning does not trip warnings-as-errors. No behavior change to the tests' actual assertions.

for more information, see https://pre-commit.ci

CedricConday · 2026-07-03T11:46:40Z

Thanks for the review @tsbinns — I've addressed all of it: on_outside is now keyword-only on both Epochs and EpochsArray, the check moved into BaseEpochs (so EpochsArray is covered) and runs after selection is applied, and the test no longer catches the warning. I also traced the CI matrix failures to three ICA tests that feed the full event file to a shorter raw — they now pass on_outside="ignore", since dropping the out-of-range events is expected there. Ready for another look when you have a moment.

CedricConday requested review from agramfort, drammock, larsoner and mscheltienne as code owners June 30, 2026 03:41

tsbinns requested changes Jul 1, 2026

View reviewed changes

CedricConday and others added 11 commits July 3, 2026 10:50

rename changelog fragment to PR number

797e8ec

[autofix.ci] apply automated fixes

244ea62

[pre-commit.ci] auto fixes from pre-commit.com hooks

1d8d166

for more information, see https://pre-commit.ci

[autofix.ci] apply automated fixes

5ab7993

Add on_outside option to control out-of-bounds events warning

7c1faed

Mirrors the on_missing pattern used for out-of-range Raw annotations (_on_missing helper): 'raise' | 'warn' (default) | 'ignore'. Addresses maintainer review on mne-toolsgh-14004.

ci: fix EpochsFIF first_samp crash, test for old env without warnings…

f283d01

…-as-errors, add missing BaseEpochs on_outside doc

docs: document on_outside param on EpochsArray (fix numpydoc/build_docs)

1e7cea9

CedricConday force-pushed the fix/warn-out-of-bounds-events branch from ed3a816 to 11f6a3b Compare July 3, 2026 11:43

[pre-commit.ci] auto fixes from pre-commit.com hooks

ebdc197

for more information, see https://pre-commit.ci

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Warn when Epochs events fall outside the raw data range (#12989)#14004

Warn when Epochs events fall outside the raw data range (#12989)#14004
CedricConday wants to merge 12 commits into
mne-tools:mainfrom
CedricConday:fix/warn-out-of-bounds-events

CedricConday commented Jun 30, 2026 •

edited

Loading

Uh oh!

tsbinns commented Jun 30, 2026

Uh oh!

CedricConday commented Jun 30, 2026

Uh oh!

tsbinns left a comment

Uh oh!

tsbinns Jul 1, 2026

Uh oh!

tsbinns Jul 1, 2026

Uh oh!

tsbinns Jul 1, 2026

Uh oh!

tsbinns Jul 1, 2026

Uh oh!

tsbinns commented Jul 1, 2026

Uh oh!

CedricConday commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

CedricConday commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was wrong

Fix

Test

Uh oh!

tsbinns commented Jun 30, 2026

Uh oh!

CedricConday commented Jun 30, 2026

Uh oh!

tsbinns left a comment

Choose a reason for hiding this comment

Uh oh!

tsbinns Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

tsbinns Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

tsbinns Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

tsbinns Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

tsbinns commented Jul 1, 2026

Uh oh!

CedricConday commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

CedricConday commented Jun 30, 2026 •

edited

Loading