[SciPy-dev] scipy.signal documentation suggestions

[Dan Lenski]

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()
    >>>

'''