Repository: mne-tools/mne-python

Issue:
Fix docstrings in notch_filter functions
### Proposed documentation enhancement

Written:

> trans_bandwidth: float
>     Width of the transition band in Hz. Only used for method='fir'.


Should be (according to the code):

> trans_bandwidth: float
>     Width of the transition band in Hz. Only used for method='fir' and method='iir'.


Discussion:
I think you're right, @chapochn would you be up for fixing this?
Thanks for checking. I think I could, not immediatly though. Another lack in the documentation is that the parameter:

> freqs[float]
>     Frequencies to notch filter in Hz, e.g. np.arange(60, 241, 60). None can only be used with the mode ‘spectrum_fit’, where an F test is used to find sinusoidal components.

can only take a range of frequencies when the method is 'fir' or 'spectrum_fit' (which is not specified). When one put the method 'iir', I get the error:

> ValueError: Multiple stop-bands can only be used with FIR filtering

If I understood correctly 'spectrum_fit' uses a method of substraction to get rid of the component, and not a filter per se? So the error message should also be updated?
> If I understood correctly 'spectrum_fit' uses a method of substraction to get rid of the component, and not a filter per se? So the error message should also be updated?

How would you update this part? To me it's okay to say that "multiple stop-bands can only be used with FIR filtering" even if whatever method you're calling isn't itself doing filtering
> I think you're right, @chapochn would you be up for fixing this?

I want to start contributing to open source.
And if the issue is still open, I would like to fix it
@itsdivya1309 I haven't work on it, so please feel free to fix!

@larsoner :
> How would you update this part? To me it's okay to say that "multiple stop-bands can only be used with FIR filtering" even if whatever method you're calling isn't itself doing filtering

I would propose to write (in the documentation of `freqs` and in the above-mentionned error message) "Multiple stop-bands can only be used with method='fir' or method='spectrum_fit'."
Sir, I'm new to open source. I've been using mne library for my research
internship and thought of this issue as one related to documentation only.
Please let me know if I'm wrong.

On Wed, 14 Jun 2023 at 11:55, Nikolai M Chapochnikov <
***@***.***> wrote:

> @itsdivya1309 <https://github.com/itsdivya1309> I haven't work on it, so
> please feel free to fix!
>
> @larsoner <https://github.com/larsoner> :
>
> How would you update this part? To me it's okay to say that "multiple
> stop-bands can only be used with FIR filtering" even if whatever method
> you're calling isn't itself doing filtering
>
> I would propose to write (in the documentation of freqs and in the
> above-mentionned error message) "Multiple stop-bands can only be used with
> method='fir' or method='spectrum_fit'."
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/mne-tools/mne-python/issues/11688#issuecomment-1590550330>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AZ2BKDPMDZQKZAUTEJDFRO3XLFKNFANCNFSM6AAAAAAX47IU3Q>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>

Yes I think it's a doc-only update
Ok, thank you. Will do it by this week.

Resolving patch:
diff --git a/mne/filter.py b/mne/filter.py
--- a/mne/filter.py
+++ b/mne/filter.py
@@ -1470,7 +1470,8 @@ def create_filter(
             if method == "iir":
                 if len(f_p1) != 1:
                     raise ValueError(
-                        "Multiple stop-bands can only be used " "with FIR filtering"
+                        "Multiple stop-bands can only be used with method='fir' "
+                        "and method='spectrum_fit'"
                     )
                 out = construct_iir_filter(
                     iir_params,
@@ -1541,15 +1542,16 @@ def notch_filter(
         Sampling rate in Hz.
     freqs : float | array of float | None
         Frequencies to notch filter in Hz, e.g. np.arange(60, 241, 60).
-        None can only be used with the mode 'spectrum_fit', where an F
-        test is used to find sinusoidal components.
+        Multiple stop-bands can only be used with method='fir'
+        and method='spectrum_fit'. None can only be used with the mode
+        'spectrum_fit', where an F test is used to find sinusoidal components.
     %(filter_length_notch)s
     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.
-        Only used for ``method='fir'``.
+        Only used for ``method='fir'`` and ``method='iir'``.
     %(method_fir)s
         'spectrum_fit' will use multi-taper estimation of sinusoidal
         components. If freqs=None and method='spectrum_fit', significant
diff --git a/mne/io/base.py b/mne/io/base.py
--- a/mne/io/base.py
+++ b/mne/io/base.py
@@ -1177,7 +1177,7 @@ def notch_filter(
             If None, ``freqs / 200`` is used.
         trans_bandwidth : float
             Width of the transition band in Hz.
-            Only used for ``method='fir'``.
+            Only used for ``method='fir'`` and ``method='iir'``.
         %(n_jobs_fir)s
         %(method_fir)s
         %(iir_params)s


Test patch: