# [Scipy-svn] r5001 - trunk/scipy/signal

scipy-svn@scip... scipy-svn@scip...
Thu Nov 6 05:57:12 CST 2008

```Author: cdavid
Date: 2008-11-06 05:57:03 -0600 (Thu, 06 Nov 2008)
New Revision: 5001

Modified:
trunk/scipy/signal/filter_design.py
Log:
Make the docstring of filter design more compliant to the numpy format.

Modified: trunk/scipy/signal/filter_design.py
===================================================================
--- trunk/scipy/signal/filter_design.py	2008-11-06 11:56:24 UTC (rev 5000)
+++ trunk/scipy/signal/filter_design.py	2008-11-06 11:57:03 UTC (rev 5001)
@@ -36,23 +36,22 @@
def freqs(b,a,worN=None,plot=None):
"""Compute frequency response of analog filter.

-    Description:
+    Given the numerator (b) and denominator (a) of a filter compute its
+    frequency response.

-       Given the numerator (b) and denominator (a) of a filter compute its
-       frequency response.
+            b[0]*(jw)**(nb-1) + b[1]*(jw)**(nb-2) + ... + b[nb-1]
+    H(w) = --------------------------------------------------------
+            a[0]*(jw)**(na-1) + a[1]*(jw)**(na-2) + ... + a[na-1]

-               b[0]*(jw)**(nb-1) + b[1]*(jw)**(nb-2) + ... + b[nb-1]
-       H(w) = --------------------------------------------------------
-               a[0]*(jw)**(na-1) + a[1]*(jw)**(na-2) + ... + a[na-1]
-
-    Inputs:
-
+    Parameters
+    ----------
b, a --- the numerator and denominator of a linear filter.
worN --- If None, then compute at 200 frequencies around the interesting
parts of the response curve (determined by pole-zero locations).
If a single integer, the compute at that many frequencies.
Otherwise, compute the response at frequencies given in worN.
-    Outputs: (w,h)
+    Returns
+    -------

w -- The frequencies at which h was computed.
h -- The frequency response.
@@ -74,19 +73,17 @@
def freqz(b, a=1, worN=None, whole=0, plot=None):
"""Compute frequency response of a digital filter.

-    Description:
+    Given the numerator (b) and denominator (a) of a digital filter compute
+    its frequency response.

-       Given the numerator (b) and denominator (a) of a digital filter compute
-       its frequency response.
+               jw               -jw            -jmw
+        jw  B(e)    b[0] + b[1]e + .... + b[m]e
+     H(e) = ---- = ------------------------------------
+               jw               -jw            -jnw
+            A(e)    a[0] + a[2]e + .... + a[n]e

-                  jw               -jw            -jmw
-           jw  B(e)    b[0] + b[1]e + .... + b[m]e
-        H(e) = ---- = ------------------------------------
-                  jw               -jw            -jnw
-               A(e)    a[0] + a[2]e + .... + a[n]e
-
-    Inputs:
-
+    Parameters
+    ----------
b, a --- the numerator and denominator of a linear filter.
worN --- If None, then compute at 512 frequencies around the unit circle.
If a single integer, the compute at that many frequencies.
@@ -95,8 +92,8 @@
unit-circle.  If whole is non-zero compute frequencies from 0
to 2*pi.

-    Outputs: (w,h)
-
+    Returns
+    -------
w -- The frequencies at which h was computed.
h -- The frequency response.

@@ -141,14 +138,16 @@
"""Return polynomial transfer function representation from zeros
and poles

-    Inputs:
+    Parameters
+    ----------

-      z, p --- sequences representing the zeros and poles.
-      k --- system gain.
+    z, p --- sequences representing the zeros and poles.
+    k --- system gain.

-    Outputs: (b,a)
+    Returns
+    -------

-      b, a --- numerator and denominator polynomials.
+    b, a --- numerator and denominator polynomials.

If some values of b are too close to 0, they are removed. In that case, a
@@ -340,34 +339,32 @@
def iirdesign(wp, ws, gpass, gstop, analog=0, ftype='ellip', output='ba'):
"""Complete IIR digital and analog filter design.

-    Description:
+    Given passband and stopband frequencies and gains construct an analog or
+    digital IIR filter of minimum order for a given basic type.  Return the
+    output in numerator, denominator ('ba') or pole-zero ('zpk') form.

-      Given passband and stopband frequencies and gains construct an analog or
-      digital IIR filter of minimum order for a given basic type.  Return the
-      output in numerator, denominator ('ba') or pole-zero ('zpk') form.
+    Parameters
+    ----------
+    wp, ws -- Passband and stopband edge frequencies, normalized from 0
+              to 1 (1 corresponds to pi radians / sample).  For example:
+                 Lowpass:   wp = 0.2,          ws = 0.3
+                 Highpass:  wp = 0.3,          ws = 0.2
+                 Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
+                 Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
+    gpass -- The maximum loss in the passband (dB).
+    gstop -- The minimum attenuation in the stopband (dB).
+    analog -- Non-zero to design an analog filter (in this case wp and
+              ws are in radians / second).
+    ftype -- The type of iir filter to design:
+               elliptic    : 'ellip'
+               Butterworth : 'butter',
+               Chebyshev I : 'cheby1',
+               Chebyshev II: 'cheby2',
+               Bessel :      'bessel'
+    output -- Type of output:  numerator/denominator ('ba') or pole-zero ('zpk')

-    Inputs:
-
-      wp, ws -- Passband and stopband edge frequencies, normalized from 0
-                to 1 (1 corresponds to pi radians / sample).  For example:
-                   Lowpass:   wp = 0.2,          ws = 0.3
-                   Highpass:  wp = 0.3,          ws = 0.2
-                   Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
-                   Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
-      gpass -- The maximum loss in the passband (dB).
-      gstop -- The minimum attenuation in the stopband (dB).
-      analog -- Non-zero to design an analog filter (in this case wp and
-                ws are in radians / second).
-      ftype -- The type of iir filter to design:
-                 elliptic    : 'ellip'
-                 Butterworth : 'butter',
-                 Chebyshev I : 'cheby1',
-                 Chebyshev II: 'cheby2',
-                 Bessel :      'bessel'
-      output -- Type of output:  numerator/denominator ('ba') or pole-zero ('zpk')
-
-    Outputs: (b,a) or (z,p,k)
-
+    Returns
+    -------
b,a -- Numerator and denominator of the iir filter.
z,p,k -- Zeros, poles, and gain of the iir filter.
"""
@@ -395,24 +392,22 @@
def iirfilter(N, Wn, rp=None, rs=None, btype='band', analog=0, ftype='butter', output='ba'):
"""IIR digital and analog filter design given order and critical points.

-    Description:
+    Design an Nth order lowpass digital or analog filter and return the filter
+    coefficients in (B,A) (numerator, denominator) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog filter and return the filter
-      coefficients in (B,A) (numerator, denominator) or (Z,P,K) form.
+    Parameters
+    ----------
+    N -- the order of the filter.
+    Wn -- a scalar or length-2 sequence giving the critical frequencies.
+    rp, rs -- For chebyshev and elliptic filters provides the maximum ripple
+              in the passband and the minimum attenuation in the stop band.
+    btype -- the type of filter (lowpass, highpass, bandpass, or bandstop).
+    analog -- non-zero to return an analog filter, otherwise
+              a digital filter is returned.
+    ftype -- the type of IIR filter (Butterworth, Cauer (Elliptic),
+             Bessel, Chebyshev1, Chebyshev2)
+    output -- 'ba' for (b,a) output, 'zpk' for (z,p,k) output.

-    Inputs:
-
-      N -- the order of the filter.
-      Wn -- a scalar or length-2 sequence giving the critical frequencies.
-      rp, rs -- For chebyshev and elliptic filters provides the maximum ripple
-                in the passband and the minimum attenuation in the stop band.
-      btype -- the type of filter (lowpass, highpass, bandpass, or bandstop).
-      analog -- non-zero to return an analog filter, otherwise
-                a digital filter is returned.
-      ftype -- the type of IIR filter (Butterworth, Cauer (Elliptic),
-               Bessel, Chebyshev1, Chebyshev2)
-      output -- 'ba' for (b,a) output, 'zpk' for (z,p,k) output.
-
"""

@@ -559,19 +554,19 @@

Returns the non-integer order for an analog band stop filter.

-    Inputs:
+    Parameters
+    ----------
+    wp -- passb edge
+    ind -- index specifying which passb edge to vary (0 or 1).
+    passb -- two element vector of fixed passband edges.
+    stopb -- two element vector of fixed stopband edges.
+    gstop -- amount in dB of attenuation in stopband.
+    gpass -- amount in dB of ripple in the passband.
+    type -- 'butter', 'cheby', or 'ellip':

-      wp -- passb edge
-      ind -- index specifying which passb edge to vary (0 or 1).
-      passb -- two element vector of fixed passband edges.
-      stopb -- two element vector of fixed stopband edges.
-      gstop -- amount in dB of attenuation in stopband.
-      gpass -- amount in dB of ripple in the passband.
-      type -- 'butter', 'cheby', or 'ellip':
-
-    Outputs: (n,)
-
-      n -- filter order (possibly non-integer)
+    Returns
+    -------
+    n -- filter order (possibly non-integer)
"""

passbC = passb.copy()
@@ -602,31 +597,29 @@
def buttord(wp, ws, gpass, gstop, analog=0):
"""Butterworth filter order selection.

-    Description:
+    Return the order of the lowest order digital Butterworth filter that loses
+    no more than gpass dB in the passband and has at least gstop dB attenuation
+    in the stopband.

-      Return the order of the lowest order digital Butterworth filter that
-      loses no more than gpass dB in the passband and has at least gstop dB
-      attenuation in the stopband.
+    Parameters
+    ----------
+    wp, ws -- Passband and stopband edge frequencies, normalized from 0
+              to 1 (1 corresponds to pi radians / sample).  For example:
+                 Lowpass:   wp = 0.2,          ws = 0.3
+                 Highpass:  wp = 0.3,          ws = 0.2
+                 Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
+                 Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
+    gpass -- The maximum loss in the passband (dB).
+    gstop -- The minimum attenuation in the stopband (dB).
+    analog -- Non-zero to design an analog filter (in this case wp and
+              ws are in radians / second).

-    Inputs:
+    Returns
+    -------
+    ord -- The lowest order for a Butterworth filter which meets specs.
+    Wn -- The Butterworth natural frequency (i.e. the "3dB frequency").
+          Should be used with scipy.signal.butter to give filter results.

-      wp, ws -- Passband and stopband edge frequencies, normalized from 0
-                to 1 (1 corresponds to pi radians / sample).  For example:
-                   Lowpass:   wp = 0.2,          ws = 0.3
-                   Highpass:  wp = 0.3,          ws = 0.2
-                   Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
-                   Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
-      gpass -- The maximum loss in the passband (dB).
-      gstop -- The minimum attenuation in the stopband (dB).
-      analog -- Non-zero to design an analog filter (in this case wp and
-                ws are in radians / second).
-
-    Outputs: (ord, Wn)
-
-      ord -- The lowest order for a Butterworth filter which meets specs.
-      Wn -- The Butterworth natural frequency (i.e. the "3dB frequency").
-            Should be used with scipy.signal.butter to give filter results.
-
"""

wp = atleast_1d(wp)
@@ -710,31 +703,29 @@
def cheb1ord(wp, ws, gpass, gstop, analog=0):
"""Chebyshev type I filter order selection.

-    Description:
+    Return the order of the lowest order digital Chebyshev Type I filter that
+    loses no more than gpass dB in the passband and has at least gstop dB
+    attenuation in the stopband.

-      Return the order of the lowest order digital Chebyshev Type I filter
-      that loses no more than gpass dB in the passband and has at least gstop dB
-      attenuation in the stopband.
+    Parameters
+    ----------
+    wp, ws -- Passband and stopband edge frequencies, normalized from 0
+              to 1 (1 corresponds to pi radians / sample).  For example:
+                 Lowpass:   wp = 0.2,          ws = 0.3
+                 Highpass:  wp = 0.3,          ws = 0.2
+                 Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
+                 Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
+    gpass -- The maximum loss in the passband (dB).
+    gstop -- The minimum attenuation in the stopband (dB).
+    analog -- Non-zero to design an analog filter (in this case wp and
+              ws are in radians / second).

-    Inputs:
+    Returns
+    -------
+    ord -- The lowest order for a Chebyshev type I filter that meets specs.
+    Wn -- The Chebyshev natural frequency (the "3dB frequency") for
+          use with scipy.signal.cheby1 to give filter results.

-      wp, ws -- Passband and stopband edge frequencies, normalized from 0
-                to 1 (1 corresponds to pi radians / sample).  For example:
-                   Lowpass:   wp = 0.2,          ws = 0.3
-                   Highpass:  wp = 0.3,          ws = 0.2
-                   Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
-                   Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
-      gpass -- The maximum loss in the passband (dB).
-      gstop -- The minimum attenuation in the stopband (dB).
-      analog -- Non-zero to design an analog filter (in this case wp and
-                ws are in radians / second).
-
-    Outputs: (ord, Wn)
-
-      ord -- The lowest order for a Chebyshev type I filter that meets specs.
-      Wn -- The Chebyshev natural frequency (the "3dB frequency") for
-            use with scipy.signal.cheby1 to give filter results.
-
"""
wp = atleast_1d(wp)
ws = atleast_1d(ws)
@@ -793,25 +784,25 @@
that loses no more than gpass dB in the passband and has at least gstop dB
attenuation in the stopband.

-    Inputs:
+    Parameters
+    ----------
+    wp, ws -- Passband and stopband edge frequencies, normalized from 0
+              to 1 (1 corresponds to pi radians / sample).  For example:
+                 Lowpass:   wp = 0.2,          ws = 0.3
+                 Highpass:  wp = 0.3,          ws = 0.2
+                 Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
+                 Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
+    gpass -- The maximum loss in the passband (dB).
+    gstop -- The minimum attenuation in the stopband (dB).
+    analog -- Non-zero to design an analog filter (in this case wp and
+              ws are in radians / second).

-      wp, ws -- Passband and stopband edge frequencies, normalized from 0
-                to 1 (1 corresponds to pi radians / sample).  For example:
-                   Lowpass:   wp = 0.2,          ws = 0.3
-                   Highpass:  wp = 0.3,          ws = 0.2
-                   Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
-                   Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
-      gpass -- The maximum loss in the passband (dB).
-      gstop -- The minimum attenuation in the stopband (dB).
-      analog -- Non-zero to design an analog filter (in this case wp and
-                ws are in radians / second).
+    Returns
+    -------
+    ord -- The lowest order for a Chebyshev type II filter that meets specs.
+    Wn -- The Chebyshev natural frequency for
+          use with scipy.signal.cheby2 to give the filter.

-    Outputs: (ord, Wn)
-
-      ord -- The lowest order for a Chebyshev type II filter that meets specs.
-      Wn -- The Chebyshev natural frequency for
-            use with scipy.signal.cheby2 to give the filter.
-
"""
wp = atleast_1d(wp)
ws = atleast_1d(ws)
@@ -888,31 +879,29 @@
def ellipord(wp, ws, gpass, gstop, analog=0):
"""Elliptic (Cauer) filter order selection.

-    Description:
+    Return the order of the lowest order digital elliptic filter that loses no
+    more than gpass dB in the passband and has at least gstop dB attenuation in
+    the stopband.

-      Return the order of the lowest order digital elliptic filter
-      that loses no more than gpass dB in the passband and has at least
-      gstop dB attenuation in the stopband.
+    Parameters
+    ----------
+    wp, ws -- Passband and stopband edge frequencies, normalized from 0
+              to 1 (1 corresponds to pi radians / sample).  For example:
+                 Lowpass:   wp = 0.2,          ws = 0.3
+                 Highpass:  wp = 0.3,          ws = 0.2
+                 Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
+                 Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
+    gpass -- The maximum loss in the passband (dB).
+    gstop -- The minimum attenuation in the stopband (dB).
+    analog -- Non-zero to design an analog filter (in this case wp and
+              ws are in radians / second).

-    Inputs:
+    Returns
+    -------
+    ord -- The lowest order for an Elliptic (Cauer) filter that meets specs.
+    Wn  -- The natural frequency for use with scipy.signal.ellip
+             to give the filter.

-      wp, ws -- Passband and stopband edge frequencies, normalized from 0
-                to 1 (1 corresponds to pi radians / sample).  For example:
-                   Lowpass:   wp = 0.2,          ws = 0.3
-                   Highpass:  wp = 0.3,          ws = 0.2
-                   Bandpass:  wp = [0.2, 0.5],   ws = [0.1, 0.6]
-                   Bandstop:  wp = [0.1, 0.6],   ws = [0.2, 0.5]
-      gpass -- The maximum loss in the passband (dB).
-      gstop -- The minimum attenuation in the stopband (dB).
-      analog -- Non-zero to design an analog filter (in this case wp and
-                ws are in radians / second).
-
-    Outputs: (ord, Wn)
-
-      ord -- The lowest order for an Elliptic (Cauer) filter that meets specs.
-      Wn  -- The natural frequency for use with scipy.signal.ellip
-               to give the filter.
-
"""
wp = atleast_1d(wp)
ws = atleast_1d(ws)
@@ -1497,21 +1486,21 @@
def kaiserord(ripple, width):
"""Design a Kaiser window to limit ripple and width of transition region.

-    Inputs:
+    Parameters
+    ----------
+    ripple -- positive number specifying maximum ripple in passband (dB)
+                and minimum ripple in stopband
+    width  -- width of transition region (normalized so that 1 corresponds
+                to pi radians / sample)

-      ripple -- positive number specifying maximum ripple in passband (dB)
-                  and minimum ripple in stopband
-      width  -- width of transition region (normalized so that 1 corresponds
-                  to pi radians / sample)
+    Returns
+    -------
+    N, beta -- the order and beta parameter for the kaiser window.

-    Outputs:
+               signal.kaiser(N,beta,sym=0) returns the window as does
+               signal.get_window(beta,N)
+               signal.get_window(('kaiser',beta),N)

-      N, beta -- the order and beta parameter for the kaiser window.
-
-                 signal.kaiser(N,beta,sym=0) returns the window as does
-                 signal.get_window(beta,N)
-                 signal.get_window(('kaiser',beta),N)
-
Uses the empirical equations discovered by Kaiser.

Oppenheim, Schafer, "Discrete-Time Signal Processing,", p.475-476.
@@ -1529,20 +1518,20 @@
def firwin(N, cutoff, width=None, window='hamming'):
"""FIR Filter Design using windowed ideal filter method.

-    Inputs:
+    Parameters
+    ----------
+    N      -- order of filter (number of taps)
+    cutoff -- cutoff frequency of filter (normalized so that 1 corresponds to
+              Nyquist or pi radians / sample)

-      N      -- order of filter (number of taps)
-      cutoff -- cutoff frequency of filter (normalized so that 1 corresponds to
-                  Nyquist or pi radians / sample)
+    width  -- if width is not None, then assume it is the approximate width of
+              the transition region (normalized so that 1 corresonds to pi)
+              for use in kaiser FIR filter design.
+    window -- desired window to use.

-      width  -- if width is not None, then assume it is the approximate width of
-                  the transition region (normalized so that 1 corresonds to pi)
-                  for use in kaiser FIR filter design.
-      window -- desired window to use.
-
-    Outputs:
-
-      h      -- coefficients of length N fir filter.
+    Returns
+    -------
+    h      -- coefficients of length N fir filter.
"""

from signaltools import get_window

```