Repository: scipy/scipy

Issue:
Add FIR filter examples to scipy.signal documentation
Here are a few examples that could easily be used to improve the docstrings and/or tutorial of scipy.signal: 

http://www.scipy.org/Cookbook/FIRFilter
http://www.scipy.org/Cookbook/FiltFilt
http://mpastell.com/2010/01/18/fir-with-scipy/ (IIRC @mpastell was OK with using that content, but I can't find an archived email that says that anymore. Matti can you confirm that this is OK?)

`signal.filtfilt` now has at least one nice example thanks to @WarrenWeckesser, and the tutorial is slowly improving mainly due to @endolith's PRs, but there's a ways to go....



Discussion:
@mpastell's examples are nice, but it is not true (perhaps better to say _no longer_ true) that "SciPy does not have a function for directly designing a high-pass FIR filter".  Check out the docstring for `scipy.signal.firwin`.   Admittedly, the examples in that docstring could use a little work; e.g. `f` is used but it isn't defined.

Also check out `firwin2` and `remez`.  Here's a recent question on stackoverflow about designing a high-pass filter with `remez`: http://stackoverflow.com/questions/27754979/python-scipy-signal-remez-high-pass-filter-design-yields-strange-transfer-functi

`<pedantic>`By the way, one wouldn't normally use `filtfilt` with a FIR filter.  A FIR filter is usually designed to have linear phase, and if the filter has linear phase, there is no advantage to applying the filter with `filtfilt`.`</pendantic>`

```
</pendantic>
```

typo :)

but yes, thanks for that remark. 

> typo :)

Stop being so pendantic. 

Yes, feel free to use the examples and modify them in anyway you want. I'm happy if they are useful to someone.
There is slightly more up to date version in Pweave examples: http://mpastell.com/pweave/examples/FIR_design.html (regarding FIR highpass), I should probably update the old blog post too. 

What I should have said first:  Yes, this is a great idea!

I put some `remez` examples here: https://gist.github.com/WarrenWeckesser/67bef61f496080aeb798

I have several other tasks to finish on my scipy to-do list before I'd work on this, so if anyone wants to expand the `remez` docstring with examples like those, feel free to use whatever you like.

Here's another example of filtfilt vs lfilter, though very similar to the one you linked to: http://dsp.stackexchange.com/a/19086/29

Could `firwin` be modified to take a btype argument so you don't need to do it by hand, similar to the IIR filter design functions?  Or make another function for that purpose that wraps it?

FWIW, here's another example that I created for a stackoverflow answer: 
http://stackoverflow.com/questions/16301569/bandpass-filter-in-python/16306891#16306891

Maybe this tutorial I wrote for MNE could be adapted:

https://martinos.org/mne/stable/auto_tutorials/plot_background_filtering.html

At least some (non-signal-processing engineer) neuroscientists I've talked to have found it to be a useful intro. Of course for SciPy it could be expanded to deal with other design methods (e.g., `remez`).

Resolving patch:
diff --git a/scipy/signal/fir_filter_design.py b/scipy/signal/fir_filter_design.py
--- a/scipy/signal/fir_filter_design.py
+++ b/scipy/signal/fir_filter_design.py
@@ -742,21 +742,80 @@ def remez(numtaps, bands, desired, weight=None, Hz=None, type='bandpass',
 
     Examples
     --------
-    For a signal sampled at 100 Hz, we want to construct a filter with a
-    passband at 20-40 Hz, and stop bands at 0-10 Hz and 45-50 Hz. Note that
-    this means that the behavior in the frequency ranges between those bands
-    is unspecified and may overshoot.
+    In these examples `remez` gets used creating a bandpass, bandstop, lowpass
+    and highpass filter.  The used parameters are the filter order, an array
+    with according frequency boundaries, the desired attenuation values and the
+    sampling frequency.  Using `freqz` the corresponding frequency response
+    gets calculated and plotted.
 
     >>> from scipy import signal
-    >>> fs = 100
-    >>> bpass = signal.remez(72, [0, 10, 20, 40, 45, 50], [0, 1, 0], fs=fs)
-    >>> freq, response = signal.freqz(bpass)
-
     >>> import matplotlib.pyplot as plt
-    >>> plt.semilogy(0.5*fs*freq/np.pi, np.abs(response), 'b-')
-    >>> plt.grid(alpha=0.25)
-    >>> plt.xlabel('Frequency (Hz)')
-    >>> plt.ylabel('Gain')
+
+    >>> def plot_response(fs, w, h, title):
+    ...     "Utility function to plot response functions"
+    ...     fig = plt.figure()
+    ...     ax = fig.add_subplot(111)
+    ...     ax.plot(0.5*fs*w/np.pi, 20*np.log10(np.abs(h)))
+    ...     ax.set_ylim(-40, 5)
+    ...     ax.set_xlim(0, 0.5*fs)
+    ...     ax.grid(True)
+    ...     ax.set_xlabel('Frequency (Hz)')
+    ...     ax.set_ylabel('Gain (dB)')
+    ...     ax.set_title(title)
+
+    This example shows a steep low pass transition according to the small
+    transition width and high filter order:
+
+    >>> fs = 22050.0       # Sample rate, Hz
+    >>> cutoff = 8000.0    # Desired cutoff frequency, Hz
+    >>> trans_width = 100  # Width of transition from pass band to stop band, Hz
+    >>> numtaps = 400      # Size of the FIR filter.
+    >>> taps = signal.remez(numtaps, [0, cutoff, cutoff + trans_width, 0.5*fs], [1, 0], Hz=fs)
+    >>> w, h = signal.freqz(taps, [1], worN=2000)
+    >>> plot_response(fs, w, h, "Low-pass Filter")
+
+    This example shows a high pass filter:
+
+    >>> fs = 22050.0       # Sample rate, Hz
+    >>> cutoff = 2000.0    # Desired cutoff frequency, Hz
+    >>> trans_width = 250  # Width of transition from pass band to stop band, Hz
+    >>> numtaps = 125      # Size of the FIR filter.
+    >>> taps = signal.remez(numtaps, [0, cutoff - trans_width, cutoff, 0.5*fs],
+    ...                     [0, 1], Hz=fs)
+    >>> w, h = signal.freqz(taps, [1], worN=2000)
+    >>> plot_response(fs, w, h, "High-pass Filter")
+
+    For a signal sampled with 22 kHz a bandpass filter with a pass band of 2-5
+    kHz gets calculated using the Remez algorithm.  The transition width is 260
+    Hz and the filter order 10:
+
+    >>> fs = 22000.0         # Sample rate, Hz
+    >>> band = [2000, 5000]  # Desired pass band, Hz
+    >>> trans_width = 260    # Width of transition from pass band to stop band, Hz
+    >>> numtaps = 10        # Size of the FIR filter.
+    >>> edges = [0, band[0] - trans_width, band[0], band[1],
+    ...          band[1] + trans_width, 0.5*fs]
+    >>> taps = signal.remez(numtaps, edges, [0, 1, 0], Hz=fs)
+    >>> w, h = signal.freqz(taps, [1], worN=2000)
+    >>> plot_response(fs, w, h, "Band-pass Filter")
+
+    It can be seen that for this bandpass filter, the low order leads to higher
+    ripple and less steep transitions.  There is very low attenuation in the
+    stop band and little overshoot in the pass band.  Of course the desired
+    gain can be better approximated with a higher filter order.
+
+    The next example shows a bandstop filter. Because of the high filter order
+    the transition is quite steep:
+
+    >>> fs = 20000.0         # Sample rate, Hz
+    >>> band = [6000, 8000]  # Desired stop band, Hz
+    >>> trans_width = 200    # Width of transition from pass band to stop band, Hz
+    >>> numtaps = 175        # Size of the FIR filter.
+    >>> edges = [0, band[0] - trans_width, band[0], band[1], band[1] + trans_width, 0.5*fs]
+    >>> taps = signal.remez(numtaps, edges, [1, 0, 1], Hz=fs)
+    >>> w, h = signal.freqz(taps, [1], worN=2000)
+    >>> plot_response(fs, w, h, "Band-stop Filter")
+
     >>> plt.show()
 
     """


Test patch: