# [SciPy-dev] scipy.signal documentation suggestions

Dan Lenski dlenski@gmail....
Thu Oct 18 22:53:24 CDT 2007

Jarrod Millman <millman <at> berkeley.edu> writes:
> Thanks a lot for the expanded docstring.  We are very interested in
> improving the documentation and appreciate any help you can give us.
> I will take a look at the new docstring you submitted.

Sounds good.  Thanks for making all this stuff work :-)

> In the meantime, please read over our current coding/documentation guidelines:
> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines

Didn't realize that docstrings were supposed to be in reST format, oops.  Here's
an attempt at getting it right, includes an example in doctest format  I hope
this version is more useful.

Dan

---

bilinear.__doc__ = ''''''Return a digital filter from an analog filter
using the bilinear transform.

The bilinear transform converts a filter in the continuous-time
domain (an analog filter) to a filter in the discrete-time
domain (a digital filter).

*Parameters*:

b : {array-like}
The numerator coefficient vector of the analog transform.
a : {array-like}
The denominator coefficient vector of the analog transform.
If ``a[0]`` is not 1, then both ``a`` and ``b`` are
normalized by ``a[0]``.
fs : {float}
The desired sampling frequency of the digital transform.
(*Default* = 1.0)

*Returns*:

bd : {array}
The numerator coefficient vector of the digital transform.
ad : {array}
The denominator coefficient vector of the digital transform.
Both ``a`` and ``b`` are normalized such that ``a[0]=1``.

*Algorithm*:

Given an analog filter, with rational transfer function in the
s-domain::

-1               -nb
b[0] + b[1]s  + ... + b[nb] s
H(z) = ----------------------------------
-1               -na
a[0] + a[1]s  + ... + a[na] s

The bilinear transform maps from the s-plane to the z-plane by
substituting ``s = (2*fs)(z-1)/(z+1)``, where ``fs`` is the
sampling frequency of the digital filter.  This gives the rational
transfer function in the z-domain::

-1                -nbd
bd[0] + bd[1]z  + ... + b[nbd] z
Y(z) = -------------------------------------- X(z)
-1                -nad
ad[0] + ad[1]z  + ... + a[nad] z

*Example*:

Consider a simple first-order low-pass analog filter, with
corner frequency ``w``.  Its transfer function is::

-1
1        0 + w s          b[0] = 0    b[1] = w
H(z) = --------- = -------------  =>
1 + s/w            -1        a[0] = 1    a[1] = w
1 + w s

A bilinear transform on this filter will produce a
digital filter which can be used as input to `lfilter`.  For example:

>>> from scipy.signal import *
>>> from numpy import *
>>> from pylab import *
>>>
>>> w = 10.0                     # corner frequency
>>> fs = 1000.0                  # sampling rate
>>>
>>> t = arange(0, 2*pi, 1/fs)
>>> x = sin(1*t) + sin(100*t)    # test signal
>>>
>>> b, a = bilinear([0,w], [1,w], fs)
>>> y = lfilter(b, a, x)
>>>
>>> plot(t, x, label="unfiltered") #doctest: +ELLIPSIS
[<matplotlib.lines.Line2D instance at ...>]
>>> plot(t, y, label="low-pass filtered") #doctest: +ELLIPSIS
[<matplotlib.lines.Line2D instance at ...>]
>>> legend() #doctest: +ELLIPSIS
<matplotlib.legend.Legend instance at ...>
>>> show()
>>>

'''

More information about the Scipy-dev mailing list