[MRG+1] Add deprecation cycle for average parameter in compute_proj…

…_exg (mne-tools#5155)

mne/channels/channels.py

@@ -883,15 +883,20 @@ def add_channels(self, add_list, force_update_info=False):
         else:
             con_axis = 0
             comp_class = type(self)
-        if not all(isinstance(inst, comp_class) for inst in add_list):
-            raise AssertionError('All input data must be of same type')
+        for inst in add_list:
+            if not isinstance(inst, comp_class):
+                raise AssertionError('All input data must be of same type, got'
+                                     ' %s and %s' % (comp_class, type(inst)))
         data = [inst._data for inst in [self] + add_list]
 
         # Make sure that all dimensions other than channel axis are the same
         compare_axes = [i for i in range(data[0].ndim) if i != con_axis]
         shapes = np.array([dat.shape for dat in data])[:, compare_axes]
-        if not ((shapes[0] - shapes) == 0).all():
-            raise AssertionError('All dimensions except channels must match')
+        for shape in shapes:
+            if not ((shapes[0] - shape) == 0).all():
+                raise AssertionError('All data dimensions except channels '
+                                     'must match, got %s != %s'
+                                     % (shapes[0], shape))
 
         # Create final data / info objects
         data = np.concatenate(data, axis=con_axis)

mne/commands/mne_compute_proj_ecg.py

@@ -61,7 +61,7 @@ def run():
                       default=True)
     parser.add_option("-a", "--average", dest="average", action="store_true",
                       help="Compute SSP after averaging",
-                      default=False)
+                      default=False)  # XXX: change to default=True in 0.17
     parser.add_option("--proj", dest="proj",
                       help="Use SSP projections from a fif file.",
                       default=None)

mne/commands/mne_compute_proj_eog.py

@@ -64,7 +64,7 @@ def run():
                       "save memory)", default=True)
     parser.add_option("-a", "--average", dest="average", action="store_true",
                       help="Compute SSP after averaging",
-                      default=False)
+                      default=False)  # XXX: change to default=True in 0.17
     parser.add_option("--proj", dest="proj",
                       help="Use SSP projections from a fif file.",
                       default=None)

mne/preprocessing/ecg.py

@@ -149,9 +149,9 @@ def find_ecg_events(raw, event_id=999, ch_name=None, tstart=0.0,
         Start detection after tstart seconds. Useful when beginning
         of run is noisy.
     l_freq : float
-        Low pass frequency.
+        Low pass frequency to apply to the ECG channel while finding events.
     h_freq : float
-        High pass frequency.
+        High pass frequency to apply to the ECG channel while finding events.
     qrs_threshold : float | str
         Between 0 and 1. qrs detection threshold. Can also be "auto" to
         automatically choose the threshold that generates a reasonable
@@ -173,6 +173,11 @@ def find_ecg_events(raw, event_id=999, ch_name=None, tstart=0.0,
         Name of channel used.
     average_pulse : float
         Estimated average pulse.
+
+    See Also
+    --------
+    create_ecg_epochs
+    compute_proj_ecg
     """
     idx_ecg = _get_ecg_channel_index(ch_name, raw)
     if idx_ecg is not None:
@@ -241,7 +246,7 @@ def create_ecg_epochs(raw, ch_name=None, event_id=999, picks=None, tmin=-0.5,
         If None (default), ECG channel is used if present. If None and no
         ECG channel is present, a synthetic ECG channel is created from
         cross channel average. Synthetic channel can only be created from
-        'meg' channels.
+        MEG channels.
     event_id : int
         The index to assign to found events
     picks : array-like of int | None (default)
@@ -251,9 +256,9 @@ def create_ecg_epochs(raw, ch_name=None, event_id=999, picks=None, tmin=-0.5,
     tmax : float
         End time after event.
     l_freq : float
-        Low pass frequency.
+        Low pass frequency to apply to the ECG channel while finding events.
     h_freq : float
-        High pass frequency.
+        High pass frequency to apply to the ECG channel while finding events.
     reject : dict | None
         Rejection parameters based on peak-to-peak amplitude.
         Valid keys are 'grad' | 'mag' | 'eeg' | 'eog' | 'ecg'.
@@ -279,7 +284,8 @@ def create_ecg_epochs(raw, ch_name=None, event_id=999, picks=None, tmin=-0.5,
         If baseline is equal to (None, None) all the time
         interval is used. If None, no correction is applied.
     preload : bool
-        Preload epochs or not.
+        Preload epochs or not (default True). Must be True if
+        keep_ecg is True.
     keep_ecg : bool
         When ECG is synthetically created (after picking), should it be added
         to the epochs? Must be False when synthetic channel is not used.
@@ -299,43 +305,52 @@ def create_ecg_epochs(raw, ch_name=None, event_id=999, picks=None, tmin=-0.5,
     -------
     ecg_epochs : instance of Epochs
         Data epoched around ECG r-peaks.
+
+    See Also
+    --------
+    find_ecg_events
+    compute_proj_ecg
+
+    Notes
+    -----
+    Filtering is only applied to the ECG channel while finding events.
+    The resulting ``ecg_epochs`` will have no filtering applied (i.e., have
+    the same filter properties as the input ``raw`` instance).
     """
     has_ecg = 'ecg' in raw or ch_name is not None
+    if keep_ecg and (has_ecg or not preload):
+        raise ValueError('keep_ecg can be True only if the ECG channel is '
+                         'created synthetically and preload=True.')
 
     events, _, _, ecg = find_ecg_events(
         raw, ch_name=ch_name, event_id=event_id, l_freq=l_freq, h_freq=h_freq,
         return_ecg=True, verbose=verbose)
 
-    # Load raw data so that add_channels works
-    raw.load_data()
     picks = np.arange(len(raw.ch_names)) if picks is None else picks
 
-    if not has_ecg:
-        ecg_raw = RawArray(
-            ecg[None],
-            create_info(ch_names=['ECG-SYN'],
-                        sfreq=raw.info['sfreq'], ch_types=['ecg']))
-        ignore = ['ch_names', 'chs', 'nchan', 'bads']
-        for k, v in raw.info.items():
-            if k not in ignore:
-                ecg_raw.info[k] = v
-        raw.add_channels([ecg_raw])
-
-    if keep_ecg:
-        if has_ecg:
-            raise ValueError('keep_ecg can be True only if the ECG channel is '
-                             'created synthetically.')
-        else:
-            picks = np.append(picks, raw.ch_names.index('ECG-SYN'))
     # create epochs around ECG events and baseline (important)
     ecg_epochs = Epochs(raw, events=events, event_id=event_id,
                         tmin=tmin, tmax=tmax, proj=False, flat=flat,
                         picks=picks, reject=reject, baseline=baseline,
                         reject_by_annotation=reject_by_annotation,
                         verbose=verbose, preload=preload)
 
-    if not has_ecg:
-        raw.drop_channels(['ECG-SYN'])
+    if keep_ecg:
+        # We know we have created a synthetic channel and epochs are preloaded
+        ecg_raw = RawArray(
+            ecg[None],
+            create_info(ch_names=['ECG-SYN'],
+                        sfreq=raw.info['sfreq'], ch_types=['ecg']),
+            first_samp=raw.first_samp)
+        ignore = ['ch_names', 'chs', 'nchan', 'bads']
+        for k, v in raw.info.items():
+            if k not in ignore:
+                ecg_raw.info[k] = v
+        syn_epochs = Epochs(ecg_raw, events=ecg_epochs.events,
+                            event_id=event_id, tmin=tmin, tmax=tmax,
+                            proj=False, picks=[0], baseline=baseline,
+                            verbose=verbose, preload=True)
+        ecg_epochs = ecg_epochs.add_channels([syn_epochs])
 
     return ecg_epochs
 

mne/preprocessing/eog.py

@@ -27,9 +27,9 @@ def find_eog_events(raw, event_id=998, l_freq=1, h_freq=10,
     event_id : int
         The index to assign to found events.
     l_freq : float
-        Low cut-off frequency in Hz.
+        Low cut-off frequency to apply to the EOG channel in Hz.
     h_freq : float
-        High cut-off frequency in Hz.
+        High cut-off frequency to apply to the EOG channel in Hz.
     filter_length : str | int | None
         Number of taps to use for filtering.
     ch_name: str | None
@@ -46,6 +46,11 @@ def find_eog_events(raw, event_id=998, l_freq=1, h_freq=10,
     -------
     eog_events : array
         Events.
+
+    See Also
+    --------
+    create_eog_epochs
+    compute_proj_eog
     """
     # Getting EOG Channel
     eog_inds = _get_eog_channel_index(ch_name, raw)
@@ -172,9 +177,9 @@ def create_eog_epochs(raw, ch_name=None, event_id=998, picks=None, tmin=-0.5,
     tmax : float
         End time after event.
     l_freq : float
-        Low pass frequency.
+        Low pass frequency to apply to the EOG channel while finding events.
     h_freq : float
-        High pass frequency.
+        High pass frequency to apply to the EOG channel while finding events.
     reject : dict | None
         Rejection parameters based on peak-to-peak amplitude.
         Valid keys are 'grad' | 'mag' | 'eeg' | 'eog' | 'ecg'.
@@ -217,6 +222,17 @@ def create_eog_epochs(raw, ch_name=None, event_id=998, picks=None, tmin=-0.5,
     -------
     eog_epochs : instance of Epochs
         Data epoched around EOG events.
+
+    See Also
+    --------
+    find_eog_events
+    compute_proj_eog
+
+    Notes
+    -----
+    Filtering is only applied to the EOG channel while finding events.
+    The resulting ``eog_epochs`` will have no filtering applied (i.e., have
+    the same filter properties as the input ``raw`` instance).
     """
     events = find_eog_events(raw, ch_name=ch_name, event_id=event_id,
                              l_freq=l_freq, h_freq=h_freq,