Repository: mne-tools/mne-python

Issue:
BrainVision: Confusing warning message since intro of annotations
When I want to read a `.vhdr` BrainVision header file, I get this  warning message:

```
Extracting parameters from xxx/sub-002_task-bandit_eeg.vhdr...
Setting channel info structure...
Used Annotations descriptions: ['Stimulus/S  1', 'Stimulus/S  2', 'Stimulus/S  3', 'Stimulus/S  4', 'Stimulus/S  5', 'Stimulus/S  6', 'Stimulus/S  7']

<ipython-input-8-7feb117556b8>:1: RuntimeWarning: 1 annotation(s) will be dropped, such as ['Comment/actiCAP Data On']. Consider using ``regexp`` to ignore annotations that do not follow a specific pattern.
  raw = mne.io.read_raw_brainvision(fname)
```

This is fine and a warning should be printed (like we did previously). However the new message does not make sense in the user context:

> Consider using ``regexp`` to ignore annotations that do not follow a specific pattern.

`regexp` is not a possible argument for `mne.io.read_raw_brainvision`, so I assume that this is some unintended spillover from the annotations refactoring.


Discussion:
@agramfort @massich 
what was the error message before?

it's this line
https://github.com/mne-tools/mne-python/blob/master/mne/io/brainvision/brainvision.py#L163
that you want to change.
As there is indeed no way to filter out some annots with the current
brainvision API shall we just
notify that some annots will be ignored without saying more?

The prior message was referring to `event_id` and that users should make use of that (potentially with regexp) 

>    event_id : dict | None
        Special events to consider in addition to those that follow the normal
        BrainVision trigger format ('###' with an optional single character
        prefix). If dict, the keys will be mapped to trigger values on the
        stimulus channel. Example: {'SyncStatus': 1; 'Pulse Artifact': 3}.
        If None or an empty dict (default), only BrainVision format events are
        added to the stimulus channel. Keys are case sensitive. "New Segment"
        markers are always dropped.

See: https://github.com/mne-tools/mne-python/blob/ad1c43beec450a1c7f4dcdcc02b38869e0a5370d/mne/io/brainvision/brainvision.py#L301-L304

I suggest we go back to that and just include, that regexps are accepted as well.
can you give it a try ?


Resolving patch:
diff --git a/mne/io/brainvision/brainvision.py b/mne/io/brainvision/brainvision.py
--- a/mne/io/brainvision/brainvision.py
+++ b/mne/io/brainvision/brainvision.py
@@ -68,8 +68,9 @@ class RawBrainVision(BaseRaw):
     event_id : dict | None
         Special events to consider in addition to those that follow the normal
         BrainVision trigger format ('###' with an optional single character
-        prefix). If dict, the keys will be mapped to trigger values on the
-        stimulus channel. Example: {'SyncStatus': 1; 'Pulse Artifact': 3}.
+        prefix, e.g., "111", "S  1", "R128", "S 21"). If dict, the keys will be
+        mapped to trigger values on the stimulus channel.
+        Example: {'SyncStatus': 1, 'Pulse Artifact': 3}.
         If None or an empty dict (default), only BrainVision format events are
         added to the stimulus channel. Keys are case sensitive. "New Segment"
         markers are always dropped.
@@ -160,9 +161,10 @@ def __init__(self, vhdr_fname, montage=None,
         events, _ = events_from_annotations(self, event_id)
         if len(dropped_desc) > 0:
             dropped = list(set(dropped_desc))
-            warn("{0} annotation(s) will be dropped, such as {1}. "
-                 "Consider using ``regexp`` to ignore annotations that "
-                 "do not follow a specific pattern."
+            warn("{0} event(s) will be dropped, such as {1}. "
+                 "Consider using the event_id parameter to parse events "
+                 "that do not follow the BrainVision format. For more "
+                 "information, see the docstring of read_raw_brainvision."
                  .format(len(dropped), dropped[:5]))
         self._create_event_ch(events, n_samples)
 
@@ -1000,7 +1002,7 @@ def read_raw_brainvision(vhdr_fname, montage=None,
         Special events to consider in addition to those that follow the normal
         BrainVision trigger format ('###' with an optional single character
         prefix). If dict, the keys will be mapped to trigger values on the
-        stimulus channel. Example: {'SyncStatus': 1; 'Pulse Artifact': 3}.
+        stimulus channel. Example: {'SyncStatus': 1, 'Pulse Artifact': 3}.
         If None or an empty dict (default), only BrainVision format events are
         added to the stimulus channel. Keys are case sensitive. "New Segment"
         markers are always dropped.


Test patch:
diff --git a/mne/io/brainvision/tests/test_brainvision.py b/mne/io/brainvision/tests/test_brainvision.py
--- a/mne/io/brainvision/tests/test_brainvision.py
+++ b/mne/io/brainvision/tests/test_brainvision.py
@@ -628,11 +628,14 @@ def test_read_vmrk_annotations():
 
 def test_read_raw_brainvision_warn_on_marker_drop():
     """Test that loading test.vhdr warns a summary of each dropped type."""
-    EXPECTED_WARN_MSG = \
-        r"1 annotation\(s\) will be dropped, such as \['SyncStatus/Sync On'\]"
+    EXPECTED_WARN_MSG = (r"1 event\(s\) will be dropped, such as "
+                         r"\[\'SyncStatus\/Sync On\'\]. Consider using the "
+                         r"event\_id parameter to parse events that do not "
+                         r"follow the BrainVision format. For more "
+                         r"information, see the docstring of "
+                         r"read_raw_brainvision.")
     with pytest.warns(RuntimeWarning, match=EXPECTED_WARN_MSG) as recwarn:
         read_raw_brainvision(vhdr_path, verbose=True)
     assert len(recwarn) == 1
 
-
 run_tests_if_main()