Repository: mne-tools/mne-python

Issue:
BUG/DOC: confusing parameter mapping in _BaseRaw.filter
l_freq : high pass filter cuttoff

h_freq : low pass filter cuttoff

l_trans_bandwidth : low pass filter trans bandwidth

h_trans_bandwidth : high pass filter trans bandwidth

cc @kevinjos @agramfort @Eric89GXL 



Discussion:
Is that actually how it works in the code? I assumed `l_trans_bandwidth` would be paired with `l_freq` meaning "lower" freq as opposed to "lowpass" freq... it is indeed confusing if later in the code we combine `l_freq - l_trans-bandwidth` and `h_freq + h_trans_bandwidth` to find the stop bands.

> Is that actually how it works in the code?

https://github.com/mne-tools/mne-python/blob/master/mne/io/base.py#L377

l_trans_width is mapped to low_pass, but the low pass cuttoff frequency is h_freq

This expresses a certain logic but can be confusing (I got user feedback)

Yeah, that is indeed confusing...

yeah, I have found this difficult as well

We should change this and swap the parameter semantics. The good part: no deprecation neede, defaults remain the same, also I'm not sure how many people actually change defaults here. The bad part: we need to announce it, it's a bad thing when the meaning of parameters becomes the opposite.

oups... to me it's indeed a bug fix more than an API change... Let's just document this change. I doubt anybody touched it manually.


Resolving patch:
diff --git a/mne/filter.py b/mne/filter.py
--- a/mne/filter.py
+++ b/mne/filter.py
@@ -559,10 +559,13 @@ def band_pass_filter(x, Fs, Fp1, Fp2, filter_length='10s',
         used (faster for long signals). If str, a human-readable time in
         units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
         to the shortest power-of-two length at least that duration.
+        Not used for 'iir' filters.
     l_trans_bandwidth : float
         Width of the transition band at the low cut-off frequency in Hz.
+        Not used if 'order' is specified in iir_params.
     h_trans_bandwidth : float
         Width of the transition band at the high cut-off frequency in Hz.
+        Not used if 'order' is specified in iir_params.
     method : str
         'fft' will use overlap-add FIR filtering, 'iir' will use IIR
         forward-backward filtering (via filtfilt).
@@ -659,10 +662,13 @@ def band_stop_filter(x, Fs, Fp1, Fp2, filter_length='10s',
         used (faster for long signals). If str, a human-readable time in
         units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
         to the shortest power-of-two length at least that duration.
+        Not used for 'iir' filters.
     l_trans_bandwidth : float
         Width of the transition band at the low cut-off frequency in Hz.
+        Not used if 'order' is specified in iir_params.
     h_trans_bandwidth : float
         Width of the transition band at the high cut-off frequency in Hz.
+        Not used if 'order' is specified in iir_params.
     method : str
         'fft' will use overlap-add FIR filtering, 'iir' will use IIR
         forward-backward filtering (via filtfilt).
@@ -767,8 +773,10 @@ def low_pass_filter(x, Fs, Fp, filter_length='10s', trans_bandwidth=0.5,
         used (faster for long signals). If str, a human-readable time in
         units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
         to the shortest power-of-two length at least that duration.
+        Not used for 'iir' filters.
     trans_bandwidth : float
-        Width of the transition band in Hz.
+        Width of the transition band in Hz. Not used if 'order' is specified
+        in iir_params.
     method : str
         'fft' will use overlap-add FIR filtering, 'iir' will use IIR
         forward-backward filtering (via filtfilt).
@@ -850,8 +858,10 @@ def high_pass_filter(x, Fs, Fp, filter_length='10s', trans_bandwidth=0.5,
         used (faster for long signals). If str, a human-readable time in
         units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
         to the shortest power-of-two length at least that duration.
+        Not used for 'iir' filters.
     trans_bandwidth : float
-        Width of the transition band in Hz.
+        Width of the transition band in Hz. Not used if 'order' is
+        specified in iir_params.
     method : str
         'fft' will use overlap-add FIR filtering, 'iir' will use IIR
         forward-backward filtering (via filtfilt).
@@ -939,11 +949,13 @@ def notch_filter(x, Fs, freqs, filter_length='10s', notch_widths=None,
         used (faster for long signals). If str, a human-readable time in
         units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
         to the shortest power-of-two length at least that duration.
+        Not used for 'iir' filters.
     notch_widths : float | array of float | None
         Width of the stop band (centred at each freq in freqs) in Hz.
         If None, freqs / 200 is used.
     trans_bandwidth : float
-        Width of the transition band in Hz.
+        Width of the transition band in Hz. Not used if 'order' is
+        specified in iir_params.
     method : str
         'fft' will use overlap-add FIR filtering, 'iir' will use IIR
         forward-backward filtering (via filtfilt). 'spectrum_fit' will
diff --git a/mne/io/base.py b/mne/io/base.py
--- a/mne/io/base.py
+++ b/mne/io/base.py
@@ -317,10 +317,15 @@ def filter(self, l_freq, h_freq, picks=None, filter_length='10s',
             used (faster for long signals). If str, a human-readable time in
             units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
             to the shortest power-of-two length at least that duration.
+            Not used for 'iir' filters.
         l_trans_bandwidth : float
-            Width of the transition band at the low cut-off frequency in Hz.
+            Width of the transition band at the low cut-off frequency in Hz
+            (high pass or cutoff 1 in bandpass). Not used if 'order' is
+            specified in iir_params.
         h_trans_bandwidth : float
-            Width of the transition band at the high cut-off frequency in Hz.
+            Width of the transition band at the high cut-off frequency in Hz
+            (low pass or cutoff 2 in bandpass). Not used if 'order' is
+            specified in iir_params.
         n_jobs : int | str
             Number of jobs to run in parallel. Can be 'cuda' if scikits.cuda
             is installed properly, CUDA is initialized, and method='fft'.
@@ -374,14 +379,14 @@ def filter(self, l_freq, h_freq, picks=None, filter_length='10s',
             logger.info('Low-pass filtering at %0.2g Hz' % h_freq)
             low_pass_filter(self._data, fs, h_freq,
                             filter_length=filter_length,
-                            trans_bandwidth=l_trans_bandwidth, method=method,
+                            trans_bandwidth=h_trans_bandwidth, method=method,
                             iir_params=iir_params, picks=picks, n_jobs=n_jobs,
                             copy=False)
         if l_freq is not None and h_freq is None:
             logger.info('High-pass filtering at %0.2g Hz' % l_freq)
             high_pass_filter(self._data, fs, l_freq,
                              filter_length=filter_length,
-                             trans_bandwidth=h_trans_bandwidth, method=method,
+                             trans_bandwidth=l_trans_bandwidth, method=method,
                              iir_params=iir_params, picks=picks, n_jobs=n_jobs,
                              copy=False)
         if l_freq is not None and h_freq is not None:
@@ -436,6 +441,7 @@ def notch_filter(self, freqs, picks=None, filter_length='10s',
             used (faster for long signals). If str, a human-readable time in
             units of "s" or "ms" (e.g., "10s" or "5500ms") will be converted
             to the shortest power-of-two length at least that duration.
+            Not used for 'iir' filters.
         notch_widths : float | array of float | None
             Width of each stop band (centred at each freq in freqs) in Hz.
             If None, freqs / 200 is used.


Test patch: