refactor function name and inputs

Author: sagi-ezri

scipy/signal/__init__.py

@@ -86,7 +86,7 @@
                     -- defined as pass and stop bands.
    firwin2       -- Windowed FIR filter design, with arbitrary frequency
                     -- response.
-   fwind1        -- Windowed FIR filter design, with frequency response for 
+   firwin_2d        -- Windowed FIR filter design, with frequency response for 
                     -- 2D using 1D design.
    freqs         -- Analog filter frequency response from TF coefficients.
    freqs_zpk     -- Analog filter frequency response from ZPK coefficients.

scipy/signal/_fir_filter_design.py

@@ -16,7 +16,7 @@
 
 
 __all__ = ['kaiser_beta', 'kaiser_atten', 'kaiserord',
-           'firwin', 'firwin2', 'fwind1', 'remez', 'firls', 'minimum_phase']
+           'firwin', 'firwin2', 'firwin_2d', 'remez', 'firls', 'minimum_phase']
 
 
 # Some notes on function parameters:
@@ -1283,15 +1283,15 @@ def minimum_phase(h: np.ndarray,
     return h_minimum[:n_out]
 
 
-def fwind1(hsize, window, *, fc=None, fs=2, circular=False):
+def firwin_2d(hsize, window, *, fc=None, fs=2, circular=False, pass_zero=True, scale=True):
     """
     2D FIR filter design using the window method.
 
     This function computes the coefficients of a 2D finite impulse response
     filter. The filter is separable with linear phase; it will be designed
     as a product of two 1D filters with dimensions defined by `hsize`.
     Additionally, it can create approximately circularly symmetric 2-D windows.
-
+    
     Parameters
     ----------
     hsize : tuple or list of length 2
@@ -1302,79 +1302,41 @@ def fwind1(hsize, window, *, fc=None, fs=2, circular=False):
         Desired window to use for each 1D filter or a single window type 
         for creating circularly symmetric 2-D windows. Each element should be
         a string or tuple of string and parameter values. See
-        '~scipy.signal.get_window' for a list of windows and required
+        `~scipy.signal.get_window` for a list of windows and required
         parameters.
     fc : float or 1-D array_like, optional
-        Cutoff frequency of filter (expressed in the same units as `fs`).
-        Required if `circular` is False.
+        Cutoff frequency of the filter in the same units as `fs`. This defines
+        the frequency at which the filter's gain drops to approximately -6 dB
+        (half power) in a low-pass or high-pass filter. For multi-band filters,
+        `fc` can be an array of cutoff frequencies (i.e., band edges) in the 
+        range [0, fs/2], with each band specified in pairs. Required if 
+        `circular` is False.
     fs : float, optional
         The sampling frequency of the signal. Default is 2.
     circular : bool, optional
         Whether to create a circularly symmetric 2-D window. Default is False.
+    pass_zero : {True, False, 'bandpass', 'lowpass', 'highpass', 'bandstop'}, optional
+        If True, the gain at the frequency 0 (i.e., the "DC gain") is 1.
+        If False, the DC gain is 0. Can also be a string argument for the
+        desired filter type (equivalent to ``btype`` in IIR design functions).
+
+        .. versionadded:: 1.3.0
+           Support for string arguments.
+    scale : bool, optional
+        Set to True to scale the coefficients so that the frequency
+        response is exactly unity at a certain frequency.
+        That frequency is either:
+
+        - 0 (DC) if the first passband starts at 0 (i.e. pass_zero
+          is True)
+        - `fs/2` (the Nyquist frequency) if the first passband ends at
+          `fs/2` (i.e the filter is a single band highpass filter);
+          center of first passband otherwise
 
     Returns
     -------
     filter_2d : (hsize[0], hsize[1]) ndarray
         Coefficients of 2D FIR filter.
-
-    Raises
-    ------
-    ValueError
-        If `hsize` and `window` are not 2-element tuples or lists.
-        If `cutoff` is None when `circular` is True.
-        If `cutoff` is outside the range [0, fs / 2] and `circular` is False.
-        If any of the elements in `window` are not recognized.
-    RuntimeError
-        If `firwin` fails to converge when designing the filter.
-
-    See Also
-    --------
-    scipy.signal.firwin, scipy.signal.get_window
-
-    Examples
-    --------
-    Generate a 5x5 low-pass filter with cutoff frequency 0.1.
-
-    >>> import numpy as np
-    >>> from scipy.signal import get_window
-    >>> from scipy.signal import fwind1
-    >>> hsize = (5, 5)
-    >>> window = (("kaiser", 5.0), ("kaiser", 5.0))
-    >>> fc = 0.1
-    >>> filter_2d = fwind1(hsize, window, fc=fc)
-    >>> filter_2d
-    array([[0.00025366, 0.00401662, 0.00738617, 0.00401662, 0.00025366],
-           [0.00401662, 0.06360159, 0.11695714, 0.06360159, 0.00401662],
-           [0.00738617, 0.11695714, 0.21507283, 0.11695714, 0.00738617],
-           [0.00401662, 0.06360159, 0.11695714, 0.06360159, 0.00401662],
-           [0.00025366, 0.00401662, 0.00738617, 0.00401662, 0.00025366]])
-
-    Generate a circularly symmetric 5x5 low-pass filter with Hamming window.
-
-    >>> filter_2d = fwind1((5, 5), 'hamming', fc=fc, circular=True)
-    >>> filter_2d
-    array([[-0.00020354, -0.00020354, -0.00020354, -0.00020354, -0.00020354],
-           [-0.00020354,  0.01506844,  0.09907658,  0.01506844, -0.00020354],
-           [-0.00020354,  0.09907658, -0.00020354,  0.09907658, -0.00020354],
-           [-0.00020354,  0.01506844,  0.09907658,  0.01506844, -0.00020354],
-           [-0.00020354, -0.00020354, -0.00020354, -0.00020354, -0.00020354]])
-
-    Plotting the generated 2D filters (optional).
-
-    >>> import matplotlib.pyplot as plt
-    >>> hsize, fc = (50, 50), 0.05
-    >>> window = (("kaiser", 5.0), ("kaiser", 5.0))
-    >>> filter0_2d = fwind1(hsize, window, fc=fc)
-    >>> filter1_2d = fwind1((50, 50), 'hamming', fc=fc, circular=True)
-    ...
-    >>> fg, (ax0, ax1) = plt.subplots(1, 2, tight_layout=True, figsize=(6.5, 3.5))
-    >>> ax0.set_title("Product of 2 Windows")
-    >>> im0 = ax0.imshow(filter0_2d, cmap='viridis', origin='lower', aspect='equal')
-    >>> fg.colorbar(im0, ax=ax0, shrink=0.7)
-    >>> ax1.set_title("Circular Window")
-    >>> im1 = ax1.imshow(filter1_2d, cmap='plasma', origin='lower', aspect='equal')
-    >>> fg.colorbar(im1, ax=ax1, shrink=0.7)
-    >>> plt.show()
     """
     if len(hsize) != 2:
             raise ValueError("hsize must be a 2-element tuple or list")

scipy/signal/fir_filter_design.py

@@ -7,7 +7,7 @@
 __all__ = [  # noqa: F822
     'kaiser_beta', 'kaiser_atten', 'kaiserord',
     'firwin', 'firwin2', 'remez', 'firls', 'minimum_phase',
-    'fwind1',
+    'firwin_2d',
 ]
 
 

scipy/signal/tests/test_fir_filter_design.py

@@ -12,7 +12,7 @@
 from scipy.signal import kaiser_beta, kaiser_atten, kaiserord, \
     firwin, firwin2, freqz, remez, firls, minimum_phase, \
     convolve2d
-from scipy.signal._fir_filter_design import fwind1
+from scipy.signal._fir_filter_design import firwin_2d
 
 def test_kaiser_beta():
     b = kaiser_beta(58.7)
@@ -654,36 +654,36 @@ def test_hilbert(self):
         xp_assert_close(m, k, rtol=2e-3)
 
 
-class TestFwind1:
+class Testfirwin_2d:
     def test_invalid_args(self):
         with pytest.raises(ValueError, 
                            match="hsize must be a 2-element tuple or list"):
-            fwind1((50,), window=(("kaiser", 5.0), "boxcar"), fc=0.4)
+            firwin_2d((50,), window=(("kaiser", 5.0), "boxcar"), fc=0.4)
 
         with pytest.raises(ValueError, 
                            match="window must be a 2-element tuple or list"):
-            fwind1((51, 51), window=("hamming",), fc=0.5)
+            firwin_2d((51, 51), window=("hamming",), fc=0.5)
 
         with pytest.raises(ValueError, 
                            match="window must be a 2-element tuple or list"):
-            fwind1((51, 51), window="invalid_window", fc=0.5)
+            firwin_2d((51, 51), window="invalid_window", fc=0.5)
 
     def test_filter_design(self):
         hsize = (51, 51)
         window = (("kaiser", 8.0), ("kaiser", 8.0))
         fc = 0.4
-        taps_kaiser = fwind1(hsize, window, fc=fc)
+        taps_kaiser = firwin_2d(hsize, window, fc=fc)
         assert taps_kaiser.shape == (51, 51)
 
         window = ("hamming", "hamming")
-        taps_hamming = fwind1(hsize, window, fc=fc)
+        taps_hamming = firwin_2d(hsize, window, fc=fc)
         assert taps_hamming.shape == (51, 51)
 
     def test_impulse_response(self):
         hsize = (31, 31)
         window = ("hamming", "hamming")
         fc = 0.4
-        taps = fwind1(hsize, window, fc=fc)
+        taps = firwin_2d(hsize, window, fc=fc)
 
         impulse = np.zeros((63, 63))
         impulse[31, 31] = 1
@@ -697,7 +697,7 @@ def test_frequency_response(self):
         hsize = (31, 31)
         window = ("hamming", "hamming")
         fc = 0.4
-        taps = fwind1(hsize, window, fc=fc)
+        taps = firwin_2d(hsize, window, fc=fc)
 
         freq_response = fftshift(fft2(taps))
 
@@ -711,13 +711,13 @@ def test_symmetry(self):
         hsize = (51, 51)
         window = ("hamming", "hamming")
         fc = 0.4
-        taps = fwind1(hsize, window, fc=fc)
+        taps = firwin_2d(hsize, window, fc=fc)
         xp_assert_close(taps, np.flip(taps), rtol=1e-5)
 
     def test_circular_symmetry(self):
         hsize = (51, 51)
         window = "hamming"
-        taps = fwind1(hsize, window, circular=True, fc=0.5)
+        taps = firwin_2d(hsize, window, circular=True, fc=0.5)
         center = hsize[0] // 2
         for i in range(hsize[0]):
             for j in range(hsize[1]):
@@ -728,11 +728,11 @@ def test_circular_symmetry(self):
     def test_edge_case_circular(self):
         hsize = (3, 3)
         window = "hamming"
-        taps_small = fwind1(hsize, window, circular=True, fc=0.5)
+        taps_small = firwin_2d(hsize, window, circular=True, fc=0.5)
         assert taps_small.shape == (3, 3)
 
         hsize = (101, 101)
-        taps_large = fwind1(hsize, window, circular=True, fc=0.5)
+        taps_large = firwin_2d(hsize, window, circular=True, fc=0.5)
         assert taps_large.shape == (101, 101)
 
     def test_known_result(self):
@@ -745,7 +745,7 @@ def test_known_result(self):
         col_filter = firwin(hsize[1], cutoff=fc, window=window, fs=fs)
         known_result = np.outer(row_filter, col_filter)
 
-        taps = fwind1(hsize, (window, window), fc)
+        taps = firwin_2d(hsize, (window, window), fc)
         assert taps.shape == known_result.shape, (
             f"Shape mismatch: {taps.shape} vs {known_result.shape}"
         )