[SciPy-dev] scipy.signal documentation suggestions

[Dan Lenski]

Hi all,
I have been using SciPy, NumPy, and Matplotlib heavily for my nanoelectronics
PhD research the last few months, and am a huge fan.

Recently, I've started using the scipy.signal module and found the
documentation somewhat unclear.  The lfilter() function has very nice
documentation, but I was trying to convert some basic analog filters to
digital filters, and got hung up by the bilinear() function... which doesn't
document its inputs or outputs.

Having now figured out how it works, I thought I would suggest an expanded
documentation string modeled after that of lfilter(), below.

Sorry if this isn't the right place to send documentation suggestions.  I will
be happy to add more doc strings as I learn how to use this package, if anyone
wants them.

Thanks!

Dan Lenski

---

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

  Description

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

  Inputs:

    b -- The numerator coefficient vector of the analog transform in a
         1-D sequence.
    a -- The denominator coefficient vector of the analog transform in
         a 1-D sequence.  If a[0] is not 1, then both a and b are
         normalized by a[0].
    fs -- The desired sampling frequency of the digital transform.
          (*Default* = 1.0)

  Outputs: (bd, ad)

    bd -- The numerator coefficient vector of the digital transform.
    ad -- 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                           -1
                       1        0 + w   s         b[0] = 0    b[1] = w
            H(z) = --------- = -------------  =>                      -1
                    1 + s w          -1  -1       a[0] = 1    a[1] = w
                                1 + w   s

    A bilinear transform on this filter will produce a
    digital filter, with (non-normalized) transfer function:

                                 -1
                          w + w z              b[0] = w       b[1] = w
            Y(z) = ---------------------  => 
                                     -1        a[0] = w+2fs   a[1] = w-2fs
                    w+2fs + (w-2fs) z

'''