[Scipy-svn] r6263 - trunk/scipy/signal

[scipy-svn at scipy.org]

Author: warren.weckesser
Date: 2010-03-21 09:20:11 -0500 (Sun, 21 Mar 2010)
New Revision: 6263

Modified:
   trunk/scipy/signal/waveforms.py
Log:
DOC: Edit docstrings of chirp() and sweep_poly() for better reST rendering and to conform to the standard.

Modified: trunk/scipy/signal/waveforms.py
===================================================================
--- trunk/scipy/signal/waveforms.py	2010-03-21 13:27:41 UTC (rev 6262)
+++ trunk/scipy/signal/waveforms.py	2010-03-21 14:20:11 UTC (rev 6263)
@@ -146,9 +146,10 @@
 def chirp(t, f0, t1, f1, method='linear', phi=0, vertex_zero=True):
     """Frequency-swept cosine generator.
 
-    In the following, 'Hz' should be interpreted as 'cycles per time unit'; there is
-    no assumption here that the time unit is one second.  The important distinction
-    is that the units of rotation are cycles, not radians.
+    In the following, 'Hz' should be interpreted as 'cycles per time unit';
+    there is no assumption here that the time unit is one second.  The
+    important distinction is that the units of rotation are cycles, not
+    radians.
 
     Parameters
     ----------
@@ -161,28 +162,35 @@
     f1 : float
         Frequency (in Hz) of the waveform at time `t1`.
     method : {'linear', 'quadratic', 'logarithmic', 'hyperbolic'}, optional
-        Kind of frequency sweep.  If not given, `linear` is assumed.  See Notes below
-        for more details.
+        Kind of frequency sweep.  If not given, `linear` is assumed.  See
+        Notes below for more details.
     phi : float, optional
         Phase offset, in degrees. Default is 0.
     vertex_zero : bool, optional
         This parameter is only used when `method` is 'quadratic'.
-        It determines whether the vertex of the parabola that is the graph of the
-        frequency is at t=0 or t=t1.
+        It determines whether the vertex of the parabola that is the graph
+        of the frequency is at t=0 or t=t1.
 
     Returns
     -------
     A numpy array containing the signal evaluated at 't' with the requested
-    time-varying frequency.  More precisely, the function returns
+    time-varying frequency.  More precisely, the function returns:
+
         ``cos(phase + (pi/180)*phi)``
+
     where `phase` is the integral (from 0 to t) of ``2*pi*f(t)``.
     ``f(t)`` is defined below.
 
+    See Also
+    --------
+    scipy.signal.waveforms.sweep_poly
+
     Notes
     -----
-    There are four options for the `method`.  The following formulas give the
-    instantaneous frequency (in Hz) of the signal generated by `chirp()`.
-    For convenience, the shorter names shown below may also be used.
+    There are four options for the `method`.  The following formulas give
+    the instantaneous frequency (in Hz) of the signal generated by
+    `chirp()`.  For convenience, the shorter names shown below may also be
+    used.
 
     linear, lin, li:
 
@@ -190,20 +198,21 @@
 
     quadratic, quad, q:
 
-        The graph of the frequency f(t) is a parabola through (0, f0) and (t1, f1).
-        By default, the vertex of the parabola is at (0, f0).  If `vertex_zero`
-        is False, then the vertex is at (t1, f1).  The formula is:
+        The graph of the frequency f(t) is a parabola through (0, f0) and
+        (t1, f1).  By default, the vertex of the parabola is at (0, f0).
+        If `vertex_zero` is False, then the vertex is at (t1, f1).  The
+        formula is:
 
         if vertex_zero is True:
 
             ``f(t) = f0 + (f1 - f0) * t**2 / t1**2``
 
-        else
+        else:
 
             ``f(t) = f1 - (f1 - f0) * (t1 - t)**2 / t1**2``
 
-        To use a more general quadratic function, or an arbitrary polynomial,
-        use the function `scipy.signal.waveforms.sweep_poly`.
+        To use a more general quadratic function, or an arbitrary
+        polynomial, use the function `scipy.signal.waveforms.sweep_poly`.
 
     logarithmic, log, lo:
 
@@ -219,10 +228,6 @@
 
         f1 must be positive, and f0 must be greater than f1.
 
-    See Also
-    --------
-    scipy.signal.waveforms.sweep_poly
-
     """
     # 'phase' is computed in _chirp_phase, to make testing easier.
     phase = _chirp_phase(t, f0, t1, f1, method, vertex_zero)
@@ -273,11 +278,12 @@
 
 
 def sweep_poly(t, poly, phi=0):
-    """Frequency-swept cosine generator, with a time-dependent frequency specified
-    as a polynomial.
+    """Frequency-swept cosine generator, with a time-dependent frequency
+    specified as a polynomial.
 
-    This function generates a sinusoidal function whose instantaneous frequency
-    varies with time.  The frequency at time `t` is given by the polynomial `poly`.
+    This function generates a sinusoidal function whose instantaneous
+    frequency varies with time.  The frequency at time `t` is given by
+    the polynomial `poly`.
 
     Parameters
     ----------
@@ -288,10 +294,14 @@
         a list or ndarray of length n, then the elements of `poly` are
         the coefficients of the polynomial, and the instantaneous
         frequency is
-            ``f(t) = poly[0]*t**(n-1) + poly[1]*t**(n-2) + ... + poly[n-1]``
+
+          ``f(t) = poly[0]*t**(n-1) + poly[1]*t**(n-2) + ... + poly[n-1]``
+
         If `poly` is an instance of numpy.poly1d, then the
         instantaneous frequency is
-            ``f(t) = poly(t)``
+
+          ``f(t) = poly(t)``
+
     phi : float, optional
         Phase offset, in degrees. Default is 0.
 
@@ -299,7 +309,9 @@
     -------
     A numpy array containing the signal evaluated at 't' with the requested
     time-varying frequency.  More precisely, the function returns
+
         ``cos(phase + (pi/180)*phi)``
+
     where `phase` is the integral (from 0 to t) of ``2 * pi * f(t)``;
     ``f(t)`` is defined above.