# [SciPy-dev] scipy.signal documentation suggestions

Dan Lenski dlenski@gmail....
Thu Oct 18 20:26:40 CDT 2007

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

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)

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

'''

```