Repository: mne-tools/mne-python

Issue:
Rename and relocate `get_edf_events`
I just noticed that we now have a new function `mne.io.get_edf_events`, which is used to extract events from the EDF family. I was thinking two things:  
1. shouldn't this belong at the top level mne. The logic behind this is that we have the function `mne.find_events` which exists there. 
2. this should be renamed `find_edf_events` to follow the naming pattern.


Discussion:
edf events are more like annotations with onset, duration + description. I
think it's a mistake to call them events which are different for MNE/Epochs
etc.

This was introduced this cycle so if we're going to change the name we should do it ASAP to avoid needing to deprecate
Unfortunately, EDF/BDF files can have events encoded either (or both) as a stim channel or in an event table. Whereas `mne.find_events` works only on the stim channel, `mne.io.get_edf_events` relies only on the event table. I'm not sure if renaming it to `find_edf_events` is a good idea, because people might get confused as to which function to use for EDF files. Granted, people could already be confused by these two functions right now, but `mne.find_events` works for all kinds of file types whereas `mne.io.get_edf_events` only works on the EDF family, which is why it should probably stay in the `io` package.
I think find_edf_events naming is more consistent

I agree it should stay in the io module

@jaeilepp?
@jaeilepp <https://github.com/jaeilepp> is gone and back home in Finland
... he left my group :'(

On Wed, Sep 20, 2017 at 2:32 PM, Clemens Brunner <notifications@github.com>
wrote:

> @jaeilepp <https://github.com/jaeilepp>?
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/mne-tools/mne-python/issues/4497#issuecomment-330836904>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AAJ1HHnj4tw-D4tSyivoQyExy3_10x8Zks5skQXLgaJpZM4O5wMx>
> .
>

Oh, I didn't know that - he added this new method recently. I can create a PR and rename it (but leave it in `io`) if you want.
please do


Resolving patch:
diff --git a/mne/io/__init__.py b/mne/io/__init__.py
--- a/mne/io/__init__.py
+++ b/mne/io/__init__.py
@@ -34,7 +34,7 @@
 from .bti import read_raw_bti
 from .cnt import read_raw_cnt
 from .ctf import read_raw_ctf
-from .edf import read_raw_edf, get_edf_events
+from .edf import read_raw_edf, find_edf_events
 from .egi import read_raw_egi
 from .kit import read_raw_kit, read_epochs_kit
 from .fiff import read_raw_fif
diff --git a/mne/io/edf/__init__.py b/mne/io/edf/__init__.py
--- a/mne/io/edf/__init__.py
+++ b/mne/io/edf/__init__.py
@@ -4,4 +4,4 @@
 #
 # License: BSD (3-clause)
 
-from .edf import read_raw_edf, get_edf_events
+from .edf import read_raw_edf, find_edf_events
diff --git a/mne/io/edf/edf.py b/mne/io/edf/edf.py
--- a/mne/io/edf/edf.py
+++ b/mne/io/edf/edf.py
@@ -23,7 +23,7 @@
 from ...utils import copy_function_doc_to_method_doc
 
 
-def get_edf_events(raw):
+def find_edf_events(raw):
     """Get original EDF events as read from the header.
 
     For GDF, the values are returned in form
@@ -62,7 +62,7 @@ def get_edf_events(raw):
     events : ndarray
         The events as they are in the file header.
     """
-    return raw.get_edf_events()
+    return raw.find_edf_events()
 
 
 class RawEDF(BaseRaw):
@@ -141,7 +141,7 @@ class RawEDF(BaseRaw):
     In addition, for GDF files, the stimulus channel is constructed from the
     events in the header. The id numbers of overlapping events are simply
     combined through addition. To get the original events from the header,
-    use function :func:`mne.io.get_edf_events`.
+    use function :func:`mne.io.find_edf_events`.
 
     See Also
     --------
@@ -333,8 +333,8 @@ def _read_segment_file(self, data, idx, fi, start, stop, cals, mult):
                                       2**17 - 1)
                 data[stim_channel_idx, :] = stim
 
-    @copy_function_doc_to_method_doc(get_edf_events)
-    def get_edf_events(self):
+    @copy_function_doc_to_method_doc(find_edf_events)
+    def find_edf_events(self):
         return self._raw_extras[0]['events']
 
 
@@ -1082,7 +1082,7 @@ def _read_gdf_header(fname, stim_channel, exclude):
                 warn_overlap = True  # Warn only once.
             data[samp:samp + dur] += id
         if warn_overlap:
-            warn('Overlapping events detected. Use get_edf_events for the '
+            warn('Overlapping events detected. Use find_edf_events for the '
                  'original events.')
         edf_info['stim_data'] = data
     edf_info['events'] = events
@@ -1224,7 +1224,7 @@ def read_raw_edf(input_fname, montage=None, eog=None, misc=None,
     header. You should use keyword ``stim_channel=-1`` to add it at the end of
     the channel list. The id numbers of overlapping events are simply combined
     through addition. To get the original events from the header, use method
-    ``raw.get_edf_events``.
+    ``raw.find_edf_events``.
 
     See Also
     --------


Test patch:
diff --git a/mne/io/edf/tests/test_edf.py b/mne/io/edf/tests/test_edf.py
--- a/mne/io/edf/tests/test_edf.py
+++ b/mne/io/edf/tests/test_edf.py
@@ -24,7 +24,7 @@
 from mne.utils import run_tests_if_main, requires_pandas, _TempDir
 from mne.io import read_raw_edf
 from mne.io.tests.test_raw import _test_raw_reader
-from mne.io.edf.edf import _parse_tal_channel, get_edf_events
+from mne.io.edf.edf import _parse_tal_channel, find_edf_events
 from mne.event import find_events
 
 warnings.simplefilter('always')
@@ -159,7 +159,7 @@ def test_stim_channel():
     data_eeglab = raw_eeglab[picks]
 
     assert_array_almost_equal(data_py, data_eeglab, 10)
-    events = get_edf_events(raw_py)
+    events = find_edf_events(raw_py)
     assert_true(len(events) - 1 == len(find_events(raw_py)))  # start not found
 
     # Test uneven sampling
@@ -188,7 +188,7 @@ def test_stim_channel():
         raw[:]
     assert_equal(len(w), 0)
 
-    events = raw_py.get_edf_events()
+    events = raw_py.find_edf_events()
     assert_true(len(events) == 0)
 
 
diff --git a/mne/io/edf/tests/test_gdf.py b/mne/io/edf/tests/test_gdf.py
--- a/mne/io/edf/tests/test_gdf.py
+++ b/mne/io/edf/tests/test_gdf.py
@@ -51,7 +51,7 @@ def test_gdf_data():
 
     # Test events are encoded to stim channel.
     events = find_events(raw)
-    evs = raw.get_edf_events()
+    evs = raw.find_edf_events()
     assert_true(all([event in evs[1] for event in events[:, 0]]))