DOC: Examples of fs usage

Author: endolith

scipy/signal/filter_design.py

@@ -2482,7 +2482,8 @@ def butter(N, Wn, btype='low', analog=False, output='ba', fs=None):
 
     Examples
     --------
-    Plot the filter's frequency response, showing the critical points:
+    Design an analog filter and plot its frequency response, showing the
+    critical points:
 
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
@@ -2498,6 +2499,27 @@ def butter(N, Wn, btype='low', analog=False, output='ba', fs=None):
     >>> plt.axvline(100, color='green') # cutoff frequency
     >>> plt.show()
 
+    Generate a signal made up of 10 Hz and 20 Hz, sampled at 1 kHz
+
+    >>> t = np.linspace(0, 1, 1000)  # 1 second
+    >>> sig = np.sin(2*pi*10*t) + np.sin(2*pi*20*t)
+    >>> fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
+    >>> ax1.plot(t, sig)
+    >>> ax1.set_title('10 Hz and 20 Hz sinusoids')
+    >>> ax1.axis([0, 1, -2, 2])
+
+    Design a digital high-pass filter at 15 Hz to remove the 10 Hz tone, and
+    apply it to the signal.  (It's recommended to use second-order sections
+    format when filtering, to avoid numerical error with transfer function
+    (``ba``) format):
+
+    >>> sos = signal.butter(10, 15, 'hp', fs=1000, output='sos')
+    >>> filtered = sosfilt(sos, sig)  # Use SOS for high-order filters
+    >>> ax2.plot(t, filtered)
+    >>> ax2.set_title('After 15 Hz high-pass filter')
+    >>> ax2.axis([0, 1, -2, 2])
+    >>> ax2.set_xlabel('Time [seconds]')
+    >>> plt.show()
     """
     return iirfilter(N, Wn, btype=btype, analog=analog,
                      output=output, ftype='butter', fs=fs)
@@ -2573,7 +2595,8 @@ def cheby1(N, rp, Wn, btype='low', analog=False, output='ba', fs=None):
 
     Examples
     --------
-    Plot the filter's frequency response, showing the critical points:
+    Design an analog filter and plot its frequency response, showing the
+    critical points:
 
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
@@ -2590,6 +2613,27 @@ def cheby1(N, rp, Wn, btype='low', analog=False, output='ba', fs=None):
     >>> plt.axhline(-5, color='green') # rp
     >>> plt.show()
 
+    Generate a signal made up of 10 Hz and 20 Hz, sampled at 1 kHz
+
+    >>> t = np.linspace(0, 1, 1000)  # 1 second
+    >>> sig = np.sin(2*pi*10*t) + np.sin(2*pi*20*t)
+    >>> fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
+    >>> ax1.plot(t, sig)
+    >>> ax1.set_title('10 Hz and 20 Hz sinusoids')
+    >>> ax1.axis([0, 1, -2, 2])
+
+    Design a digital high-pass filter at 15 Hz to remove the 10 Hz tone, and
+    apply it to the signal.  (It's recommended to use second-order sections
+    format when filtering, to avoid numerical error with transfer function
+    (``ba``) format):
+
+    >>> sos = signal.cheby1(10, 1, 15, 'hp', fs=1000, output='sos')
+    >>> filtered = sosfilt(sos, sig)  # Use SOS for high-order filters
+    >>> ax2.plot(t, filtered)
+    >>> ax2.set_title('After 15 Hz high-pass filter')
+    >>> ax2.axis([0, 1, -2, 2])
+    >>> ax2.set_xlabel('Time [seconds]')
+    >>> plt.show()
     """
     return iirfilter(N, Wn, rp=rp, btype=btype, analog=analog,
                      output=output, ftype='cheby1', fs=fs)
@@ -2660,7 +2704,8 @@ def cheby2(N, rs, Wn, btype='low', analog=False, output='ba', fs=None):
 
     Examples
     --------
-    Plot the filter's frequency response, showing the critical points:
+    Design an analog filter and plot its frequency response, showing the
+    critical points:
 
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
@@ -2677,6 +2722,27 @@ def cheby2(N, rs, Wn, btype='low', analog=False, output='ba', fs=None):
     >>> plt.axhline(-40, color='green') # rs
     >>> plt.show()
 
+    Generate a signal made up of 10 Hz and 20 Hz, sampled at 1 kHz
+
+    >>> t = np.linspace(0, 1, 1000)  # 1 second
+    >>> sig = np.sin(2*pi*10*t) + np.sin(2*pi*20*t)
+    >>> fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
+    >>> ax1.plot(t, sig)
+    >>> ax1.set_title('10 Hz and 20 Hz sinusoids')
+    >>> ax1.axis([0, 1, -2, 2])
+
+    Design a digital high-pass filter at 17 Hz to remove the 10 Hz tone, and
+    apply it to the signal.  (It's recommended to use second-order sections
+    format when filtering, to avoid numerical error with transfer function
+    (``ba``) format):
+
+    >>> sos = signal.cheby2(12, 20, 17, 'hp', fs=1000, output='sos')
+    >>> filtered = sosfilt(sos, sig)  # Use SOS for high-order filters
+    >>> ax2.plot(t, filtered)
+    >>> ax2.set_title('After 15 Hz high-pass filter')
+    >>> ax2.axis([0, 1, -2, 2])
+    >>> ax2.set_xlabel('Time [seconds]')
+    >>> plt.show()
     """
     return iirfilter(N, Wn, rs=rs, btype=btype, analog=analog,
                      output=output, ftype='cheby2', fs=fs)
@@ -2758,7 +2824,8 @@ def ellip(N, rp, rs, Wn, btype='low', analog=False, output='ba', fs=None):
 
     Examples
     --------
-    Plot the filter's frequency response, showing the critical points:
+    Design an analog filter and plot its frequency response, showing the
+    critical points:
 
     >>> from scipy import signal
     >>> import matplotlib.pyplot as plt
@@ -2776,6 +2843,27 @@ def ellip(N, rp, rs, Wn, btype='low', analog=False, output='ba', fs=None):
     >>> plt.axhline(-5, color='green') # rp
     >>> plt.show()
 
+    Generate a signal made up of 10 Hz and 20 Hz, sampled at 1 kHz
+
+    >>> t = np.linspace(0, 1, 1000)  # 1 second
+    >>> sig = np.sin(2*pi*10*t) + np.sin(2*pi*20*t)
+    >>> fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
+    >>> ax1.plot(t, sig)
+    >>> ax1.set_title('10 Hz and 20 Hz sinusoids')
+    >>> ax1.axis([0, 1, -2, 2])
+
+    Design a digital high-pass filter at 17 Hz to remove the 10 Hz tone, and
+    apply it to the signal.  (It's recommended to use second-order sections
+    format when filtering, to avoid numerical error with transfer function
+    (``ba``) format):
+
+    >>> sos = signal.ellip(8, 1, 100, 17, 'hp', fs=1000, output='sos')
+    >>> filtered = sosfilt(sos, sig)  # Use SOS for high-order filters
+    >>> ax2.plot(t, filtered)
+    >>> ax2.set_title('After 15 Hz high-pass filter')
+    >>> ax2.axis([0, 1, -2, 2])
+    >>> ax2.set_xlabel('Time [seconds]')
+    >>> plt.show()
     """
     return iirfilter(N, Wn, rs=rs, rp=rp, btype=btype, analog=analog,
                      output=output, ftype='elliptic', fs=fs)