[Scipysvn] r5001  trunk/scipy/signal
scipysvn@scip...
scipysvn@scip...
Thu Nov 6 05:57:12 CST 2008
Author: cdavid
Date: 20081106 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 20081106 11:56:24 UTC (rev 5000)
+++ trunk/scipy/signal/filter_design.py 20081106 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)**(nb1) + b[1]*(jw)**(nb2) + ... + b[nb1]
+ H(w) = 
+ a[0]*(jw)**(na1) + a[1]*(jw)**(na2) + ... + a[na1]
 b[0]*(jw)**(nb1) + b[1]*(jw)**(nb2) + ... + b[nb1]
 H(w) = 
 a[0]*(jw)**(na1) + a[1]*(jw)**(na2) + ... + a[na1]

 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 polezero 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 @@
unitcircle. If whole is nonzero 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
BadCoefficients warning is emitted.
@@ 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 polezero ('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 polezero ('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  Nonzero 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 polezero ('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  Nonzero 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 polezero ('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 length2 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  nonzero 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 length2 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  nonzero 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.

SEE ALSO butterord, cheb1ord, cheb2ord, ellipord
"""
@@ 559,19 +554,19 @@
Returns the noninteger 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 noninteger)
+ Returns
+ 
+ n  filter order (possibly noninteger)
"""
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  Nonzero 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  Nonzero 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  Nonzero 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  Nonzero 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  Nonzero 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  Nonzero 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  Nonzero 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  Nonzero 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, "DiscreteTime Signal Processing,", p.475476.
@@ 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
More information about the Scipysvn
mailing list