# [Scipy-svn] r6817 - trunk/scipy/signal

scipy-svn@scip... scipy-svn@scip...
Thu Sep 23 04:17:08 CDT 2010

```Author: rgommers
Date: 2010-09-23 04:17:07 -0500 (Thu, 23 Sep 2010)
New Revision: 6817

Modified:
trunk/scipy/signal/filter_design.py
trunk/scipy/signal/ltisys.py
Log:
DOC: make ltisys and filter_design docs conform to current documentation standard.

Modified: trunk/scipy/signal/filter_design.py
===================================================================
--- trunk/scipy/signal/filter_design.py	2010-09-22 22:59:34 UTC (rev 6816)
+++ trunk/scipy/signal/filter_design.py	2010-09-23 09:17:07 UTC (rev 6817)
@@ -33,7 +33,7 @@
w = logspace(lfreq, hfreq, N)
return w

-def freqs(b,a,worN=None,plot=None):
+def freqs(b, a, worN=None, plot=None):
"""Compute frequency response of analog filter.

Given the numerator (b) and denominator (a) of a filter compute its
@@ -46,9 +46,9 @@
Parameters
----------
b : ndarray
-        numerator of a linear filter
+        Numerator of a linear filter.
a : ndarray
-        numerator of a linear filter
+        Denominator of a linear filter.
worN : {None, int}, optional
If None, then compute at 200 frequencies around the interesting parts
of the response curve (determined by pole-zero locations).  If a single
@@ -163,7 +163,7 @@
plot(w, h)
return w, h

-def tf2zpk(b,a):
+def tf2zpk(b, a):
"""Return zero, pole, gain (z,p,k) representation from a numerator,
denominator representation of a linear filter.

@@ -177,11 +177,11 @@
Returns
-------
z : ndarray
-        zeros of the transfer function.
+        Zeros of the transfer function.
p : ndarray
-        poles of the transfer function.
+        Poles of the transfer function.
k : float
-        system gain.
+        System gain.

If some values of b are too close to 0, they are removed. In that case, a
@@ -195,25 +195,25 @@
p = roots(a)
return z, p, k

-def zpk2tf(z,p,k):
+def zpk2tf(z, p, k):
"""Return polynomial transfer function representation from zeros
and poles

Parameters
----------
z : ndarray
-        zeros of the transfer function.
+        Zeros of the transfer function.
p : ndarray
-        poles of the transfer function.
+        Poles of the transfer function.
k : float
-        system gain.
+        System gain.

Returns
-------
b : ndarray
-        numerator polynomial.
+        Numerator polynomial.
a : ndarray
-        numerator and denominator polynomials.
+        Numerator and denominator polynomials.

Note
----
@@ -234,7 +234,7 @@
a = poly(p)
return b, a

-def normalize(b,a):
+def normalize(b, a):
"""Normalize polynomial representation of a transfer function.

If values of b are too close to 0, they are removed. In that case, a
@@ -261,8 +261,8 @@
return outb, outa

-def lp2lp(b,a,wo=1.0):
-    """Return a low-pass filter with cuttoff frequency wo
+def lp2lp(b, a, wo=1.0):
+    """Return a low-pass filter with cutoff frequency `wo`
from a low-pass filter prototype with unity cutoff frequency.
"""
a,b = map(atleast_1d,(a,b))
@@ -280,8 +280,8 @@
a = a * pwo[start1]/pwo[start1:]
return normalize(b, a)

-def lp2hp(b,a,wo=1.0):
-    """Return a high-pass filter with cuttoff frequency wo
+def lp2hp(b, a, wo=1.0):
+    """Return a high-pass filter with cutoff frequency `wo`
from a low-pass filter prototype with unity cutoff frequency.
"""
a,b = map(atleast_1d,(a,b))
@@ -308,8 +308,8 @@

return normalize(outb, outa)

-def lp2bp(b,a,wo=1.0, bw=1.0):
-    """Return a band-pass filter with center frequency wo and bandwidth bw
+def lp2bp(b, a, wo=1.0, bw=1.0):
+    """Return a band-pass filter with center frequency `wo` and bandwidth `bw`
from a low-pass filter prototype with unity cutoff frequency.
"""
a,b = map(atleast_1d,(a,b))
@@ -339,8 +339,8 @@

return normalize(bprime, aprime)

-def lp2bs(b,a,wo=1,bw=1):
-    """Return a band-stop filter with center frequency wo and bandwidth bw
+def lp2bs(b, a, wo=1, bw=1):
+    """Return a band-stop filter with center frequency `wo` and bandwidth `bw`
from a low-pass filter prototype with unity cutoff frequency.
"""
a,b = map(atleast_1d,(a,b))
@@ -370,10 +370,10 @@

return normalize(bprime, aprime)

-def bilinear(b,a,fs=1.0):
+def bilinear(b, a, fs=1.0):
"""Return a digital filter from an analog filter using the bilinear transform.

-    The bilinear transform substitutes (z-1) / (z+1) for s
+    The bilinear transform substitutes ``(z-1) / (z+1``) for ``s``.
"""
fs =float(fs)
a,b = map(atleast_1d,(a,b))
@@ -413,28 +413,43 @@

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 -- Non-zero 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 pole-zero ('zpk')
+    wp, ws : float
+        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 : float
+        The maximum loss in the passband (dB).
+    gstop : float
+        The minimum attenuation in the stopband (dB).
+    analog : int, optional
+        Non-zero to design an analog filter (in this case `wp` and `ws` are in
+    ftype : str, optional
+        The type of IIR filter to design:
+
+            - elliptic    : 'ellip'
+            - Butterworth : 'butter',
+            - Chebyshev I : 'cheby1',
+            - Chebyshev II: 'cheby2',
+            - Bessel :      'bessel'
+
+    output : ['ba', 'zpk'], optional
+        Type of output:  numerator/denominator ('ba') or pole-zero ('zpk').
+        Default is 'ba'.
+
Returns
-------
-      b,a -- Numerator and denominator of the iir filter.
-      z,p,k -- Zeros, poles, and gain of the iir filter.
+    b, a :
+        Numerator and denominator of the IIR filter. Only returned if
+        ``output='ba'``.
+    z, p, k : Zeros, poles, and gain of the IIR filter. Only returned if
+    ``output='zpk'``.
+
"""

try:
@@ -465,18 +480,38 @@

Parameters
----------
-    N -- the order of the filter.
-    Wn -- a scalar or length-2 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 -- non-zero 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.
+    N : int
+        The order of the filter.
+    Wn : array_like
+        A scalar or length-2 sequence giving the critical frequencies.
+    rp : float, optional
+        For Chebyshev and elliptic filters provides the maximum ripple
+        in the passband.
+    rs : float, optional
+        For chebyshev and elliptic filters provides the minimum attenuation in
+        the stop band.
+    btype : str, optional
+        The type of filter (lowpass, highpass, bandpass, bandstop).
+        Default is bandpass.
+    analog : int, optional
+        Non-zero to return an analog filter, otherwise a digital filter is
+        returned.
+    ftype : str, optional
+        The type of IIR filter to design:

+            - elliptic    : 'ellip'
+            - Butterworth : 'butter',
+            - Chebyshev I : 'cheby1',
+            - Chebyshev II: 'cheby2',
+            - Bessel :      'bessel'
+
+    output : ['ba', 'zpk'], optional
+        Type of output:  numerator/denominator ('ba') or pole-zero ('zpk').
+        Default is 'ba'.
+
+    --------
+    butterord, cheb1ord, cheb2ord, ellipord
"""

ftype, btype, output = [x.lower() for x in (ftype, btype, output)]
@@ -551,59 +586,57 @@
def butter(N, Wn, btype='low', analog=0, output='ba'):
"""Butterworth digital and analog filter design.

-    Description:
+    Design an Nth order lowpass digital or analog Butterworth filter and return
+    the filter coefficients in (B,A) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog Butterworth filter
-      and return the filter coefficients in (B,A) or (Z,P,K) form.
-
+    --------
+    buttord.
"""
return iirfilter(N, Wn, btype=btype, analog=analog, output=output, ftype='butter')

def cheby1(N, rp, Wn, btype='low', analog=0, output='ba'):
"""Chebyshev type I digital and analog filter design.

-    Description:
+    Design an Nth order lowpass digital or analog Chebyshev type I filter and
+    return the filter coefficients in (B,A) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog Chebyshev type I filter
-      and return the filter coefficients in (B,A) or (Z,P,K) form.
-
+    --------
+    cheb1ord.
"""
return iirfilter(N, Wn, rp=rp, btype=btype, analog=analog, output=output, ftype='cheby1')

def cheby2(N, rs, Wn, btype='low', analog=0, output='ba'):
"""Chebyshev type I digital and analog filter design.

-    Description:
+    Design an Nth order lowpass digital or analog Chebyshev type I filter and
+    return the filter coefficients in (B,A) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog Chebyshev type I filter
-      and return the filter coefficients in (B,A) or (Z,P,K) form.
-
+    --------
+    cheb2ord.
"""
return iirfilter(N, Wn, rs=rs, btype=btype, analog=analog, output=output, ftype='cheby2')

def ellip(N, rp, rs, Wn, btype='low', analog=0, output='ba'):
"""Elliptic (Cauer) digital and analog filter design.

-    Description:
+    Design an Nth order lowpass digital or analog elliptic filter and return
+    the filter coefficients in (B,A) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog elliptic filter
-      and return the filter coefficients in (B,A) or (Z,P,K) form.
-
+    --------
+    ellipord.
"""
return iirfilter(N, Wn, rs=rs, rp=rp, btype=btype, analog=analog, output=output, ftype='elliptic')

def bessel(N, Wn, btype='low', analog=0, output='ba'):
"""Bessel digital and analog filter design.

-    Description:
+    Design an Nth order lowpass digital or analog Bessel filter and return the
+    filter coefficients in (B,A) or (Z,P,K) form.

-      Design an Nth order lowpass digital or analog Bessel filter
-      and return the filter coefficients in (B,A) or (Z,P,K) form.
-
"""
return iirfilter(N, Wn, btype=btype, analog=analog, output=output, ftype='bessel')

@@ -616,25 +649,31 @@

def band_stop_obj(wp, ind, passb, stopb, gpass, gstop, type):
-    """Band Stop Objective Function for order minimization
+    """Band Stop Objective Function for order minimization.

-    Description:
+    Returns the non-integer order for an analog band stop filter.

-      Returns the non-integer order for an analog band stop filter.
-
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 :
+        Edge of passband `passb`.
+    ind : int
+        Index specifying which `passb` edge to vary (0 or 1).
+    passb : array_like
+        Two element sequence of fixed passband edges.
+    stopb : array_like
+        Two element sequence of fixed stopband edges.
+    gstop : float
+        Amount of attenuation in stopband in dB.
+    gpass : float
+        Amount of ripple in the passband in dB.
+    type : ['butter', 'cheby', 'ellip']
+        Type of filter.

Returns
-------
-    n -- filter order (possibly non-integer)
+    n : scalar
+        Filter order (possibly non-integer).
"""

passbC = passb.copy()
@@ -666,27 +705,35 @@
"""Butterworth filter order selection.

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.
+    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 -- Non-zero to design an analog filter (in this case wp and
-              ws are in radians / second).
+    wp, ws : float
+        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 : float
+        The maximum loss in the passband (dB).
+    gstop : float
+        The minimum attenuation in the stopband (dB).
+    analog : int, optional
+        Non-zero to design an analog filter (in this case `wp` and `ws` are in
+
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.
+    ord : int
+        The lowest order for a Butterworth filter which meets specs.
+    wn : ndarray or float
+        The Butterworth natural frequency (i.e. the "3dB frequency").  Should
+        be used with `butter` to give filter results.

"""

@@ -772,27 +819,35 @@
"""Chebyshev type I filter order selection.

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
+    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 -- Non-zero to design an analog filter (in this case wp and
-              ws are in radians / second).
+    wp, ws : float
+        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 : float
+        The maximum loss in the passband (dB).
+    gstop : float
+        The minimum attenuation in the stopband (dB).
+    analog : int, optional
+        Non-zero to design an analog filter (in this case `wp` and `ws` are in
+
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.
+    ord : int
+        The lowest order for a Chebyshev type I filter that meets specs.
+    wn : ndarray or float
+        The Chebyshev natural frequency (the "3dB frequency") for use with
+        `cheby1` to give filter results.

"""
wp = atleast_1d(wp)
@@ -854,22 +909,30 @@

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 -- Non-zero to design an analog filter (in this case wp and
-              ws are in radians / second).
+    wp, ws : float
+        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 : float
+        The maximum loss in the passband (dB).
+    gstop : float
+        The minimum attenuation in the stopband (dB).
+    analog : int, optional
+        Non-zero to design an analog filter (in this case `wp` and `ws` are in
+
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.
+    ord : int
+        The lowest order for a Chebyshev type II filter that meets specs.
+    wn : ndarray or float
+        The Chebyshev natural frequency (the "3dB frequency") for use with
+        `cheby2` to give filter results.

"""
wp = atleast_1d(wp)
@@ -953,22 +1016,30 @@

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 -- Non-zero to design an analog filter (in this case wp and
-              ws are in radians / second).
+    wp, ws : float
+        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 : float
+        The maximum loss in the passband (dB).
+    gstop : float
+        The minimum attenuation in the stopband (dB).
+    analog : int, optional
+        Non-zero to design an analog filter (in this case `wp` and `ws` are in
+
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.
+    ------
+    ord : int
+        The lowest order for  an Elliptic (Cauer) filter that meets specs.
+    wn : ndarray or float
+        The Chebyshev natural frequency (the "3dB frequency") for use with
+        `ellip` to give filter results.-

"""
wp = atleast_1d(wp)
@@ -1031,10 +1102,9 @@
k = 1
return z, p, k

-def cheb1ap(N,rp):
-    """Return (z,p,k) zero, pole, gain for Nth order Chebyshev type I
-    lowpass analog filter prototype with rp decibels of ripple
-    in the passband.
+def cheb1ap(N, rp):
+    """Return (z,p,k) zero, pole, gain for Nth order Chebyshev type I lowpass
+    analog filter prototype with `rp` decibels of ripple in the passband.
"""
z = []
eps = numpy.sqrt(10**(0.1*rp)-1.0)
@@ -1048,10 +1118,9 @@
return z, p, k
pass

-def cheb2ap(N,rs):
-    """Return (z,p,k) zero, pole, gain for Nth order Chebyshev type II
-    lowpass analog filter prototype with rs decibels of ripple
-    in the stopband.
+def cheb2ap(N, rs):
+    """Return (z,p,k) zero, pole, gain for Nth order Chebyshev type II lowpass
+    analog filter prototype with `rs` decibels of ripple in the stopband.
"""
de = 1.0/sqrt(10**(0.1*rs)-1)
mu = arcsinh(1.0/de)/N
@@ -1093,13 +1162,16 @@
r = 1e20
return abs(r)

-def ellipap(N,rp,rs):
+def ellipap(N, rp, rs):
"""Return (z,p,k) zeros, poles, and gain of an Nth order normalized
-    prototype elliptic analog lowpass filter with rp decibels of ripple
-    in the passband and a stopband rs decibels down.
+    prototype elliptic analog lowpass filter with `rp` decibels of ripple in
+    the passband and a stopband `rs` decibels down.

-    See Chapter 12 and Chapter 5 of "Filter Design for Signal Processing",
-    by Lutova, Tosic, and Evans.  This is
+    References
+    ----------
+    Lutova, Tosic, and Evans, "Filter Design for Signal Processing", Chapters 5
+    and 12.
+
"""
if N == 1:
p = -sqrt(1.0/(10**(0.1*rp)-1.0))
@@ -1160,8 +1232,8 @@

def besselap(N):
-    """Return (z,p,k) zero, pole, gain for analog prototype of an Nth
-    order Bessel filter."""
+    """Return (z,p,k) zero, pole, gain for analog prototype of an Nth order
+    Bessel filter."""
z = []
k = 1
if N == 0:

Modified: trunk/scipy/signal/ltisys.py
===================================================================
--- trunk/scipy/signal/ltisys.py	2010-09-22 22:59:34 UTC (rev 6816)
+++ trunk/scipy/signal/ltisys.py	2010-09-23 09:17:07 UTC (rev 6817)
@@ -127,7 +127,7 @@
----------
A, B, C, D : ndarray
State-space representation of linear system.
-    input : int
+    input : int, optional
For multiple-input systems, the input to use.

Returns
@@ -174,7 +174,7 @@

return num, den

-def zpk2ss(z,p,k):
+def zpk2ss(z, p, k):
"""Zero-pole-gain representation to state-space representation

Parameters
@@ -192,17 +192,23 @@
"""
return tf2ss(*zpk2tf(z,p,k))

-def ss2zpk(A,B,C,D,input=0):
+def ss2zpk(A, B, C, D, input=0):
"""State-space representation to zero-pole-gain representation.

-    Inputs:
+    Parameters
+    ----------
+    A, B, C, D : ndarray
+        State-space representation of linear system.
+    input : int, optional
+        For multiple-input systems, the input to use.

-      A, B, C, D -- state-space matrices.
-      input -- for multiple-input systems, the input to use.
+    Returns
+    -------
+    z, p : sequence
+        Zeros and poles.
+    k : float
+        System gain.

-    Outputs:
-
-      z, p, k -- zeros and poles in sequences and gain constant.
"""
return tf2zpk(*ss2tf(A,B,C,D,input=input))

@@ -501,21 +507,21 @@
def _default_response_times(A, n):
"""Compute a reasonable set of time samples for the response time.

-    This function is used by impulse(), impulse2(), step() and step2()
+    This function is used by `impulse`, `impulse2`, `step` and `step2`
to compute the response time when the `T` argument to the function
is None.

Parameters
----------
-    A : square ndarray
-        The system matrix.
+    A : ndarray
+        The system matrix, which is square.
n : int
The number of time samples to generate.

Returns
-------
-    t : ndarray, 1D
-        The 1D array of length `n` of time samples at which the response
+    t : ndarray
+        The 1-D array of length `n` of time samples at which the response
is to be computed.
"""
# Create a reasonable time interval.  This could use some more work.
@@ -546,10 +552,11 @@

Returns
-------
-    T : 1D ndarray
-        Time points.
-    yout : 1D ndarray
-        Impulse response of the system (except for singularities at zero).
+    T : ndarray
+        A 1-D array of time points.
+    yout : ndarray
+        A 1-D array containing the impulse response of the system (except for
+        singularities at zero).

"""
if isinstance(system, lti):
@@ -686,7 +693,7 @@

def step2(system, X0=None, T=None, N=None, **kwargs):
"""Step response of continuous-time system.
-
+
This function is functionally the same as `scipy.signal.step`, but
it uses the function `scipy.signal.lsim2` to compute the step
response.

```