[Scipy-svn] r6410 - trunk/scipy/signal
scipy-svn at scipy.org
scipy-svn at scipy.org
Mon May 24 09:12:19 EDT 2010
Author: rgommers
Date: 2010-05-24 08:12:19 -0500 (Mon, 24 May 2010)
New Revision: 6410
Modified:
trunk/scipy/signal/filter_design.py
trunk/scipy/signal/ltisys.py
trunk/scipy/signal/signaltools.py
trunk/scipy/signal/waveforms.py
trunk/scipy/signal/wavelets.py
Log:
DOC: merge wiki edits - signal module.
Modified: trunk/scipy/signal/filter_design.py
===================================================================
--- trunk/scipy/signal/filter_design.py 2010-05-24 13:11:58 UTC (rev 6409)
+++ trunk/scipy/signal/filter_design.py 2010-05-24 13:12:19 UTC (rev 6410)
@@ -78,16 +78,16 @@
def freqz(b, a=1, worN=None, whole=0, plot=None):
"""
- Compute frequency response of a digital filter.
+ Compute the frequency response of a digital filter.
- Given the numerator (b) and denominator (a) of a digital filter compute
- its frequency response.
+ Given the numerator ``b`` and denominator ``a`` of a digital filter compute
+ its frequency response::
jw -jw -jmw
jw B(e) b[0] + b[1]e + .... + b[m]e
H(e) = ---- = ------------------------------------
jw -jw -jnw
- A(e) a[0] + a[2]e + .... + a[n]e
+ A(e) a[0] + a[1]e + .... + a[n]e
Parameters
----------
@@ -110,6 +110,29 @@
h : ndarray
The frequency response.
+ Examples
+ --------
+
+ >>> b = firwin(80, 0.5, window=('kaiser', 8))
+ >>> h, w = freqz(b)
+
+ >>> import matplotlib.pyplot as plt
+ >>> fig = plt.figure()
+ >>> plt.title('Digital filter frequency response')
+ >>> ax1 = fig.add_subplot(111)
+
+ >>> plt.semilogy(h, np.abs(w), 'b')
+ >>> plt.ylabel('Amplitude (dB)', color='b')
+ >>> plt.xlabel('Frequency (rad/sample)')
+ >>> plt.grid()
+ >>> plt.legend()
+
+ >>> ax2 = ax1.twinx()
+ >>> angles = np.unwrap(np.angle(w))
+ >>> plt.plot(h, angles, 'g')
+ >>> plt.ylabel('Angle (radians)', color='g')
+ >>> plt.show()
+
"""
b, a = map(atleast_1d, (b,a))
if whole:
Modified: trunk/scipy/signal/ltisys.py
===================================================================
--- trunk/scipy/signal/ltisys.py 2010-05-24 13:11:58 UTC (rev 6409)
+++ trunk/scipy/signal/ltisys.py 2010-05-24 13:12:19 UTC (rev 6410)
@@ -295,17 +295,20 @@
def lsim2(system, U=None, T=None, X0=None, **kwargs):
- """Simulate output of a continuous-time linear system, by using
+ """
+ Simulate output of a continuous-time linear system, by using
the ODE solver `scipy.integrate.odeint`.
Parameters
----------
system : an instance of the LTI class or a tuple describing the system.
The following gives the number of elements in the tuple and
- the interpretation.
- 2 (num, den)
- 3 (zeros, poles, gain)
- 4 (A, B, C, D)
+ the interpretation:
+
+ * 2: (num, den)
+ * 3: (zeros, poles, gain)
+ * 4: (A, B, C, D)
+
U : ndarray or array-like (1D or 2D), optional
An input array describing the input at each time T. Linear
interpolation is used between given times. If there are
@@ -319,7 +322,7 @@
X0 : ndarray or array-like (1D), optional
The initial condition of the state vector. If `X0` is not
given, the initial conditions are assumed to be 0.
- **kwargs :
+ kwargs : dict
Additional keyword arguments are passed on to the function
odeint. See the notes below for more details.
@@ -395,16 +398,19 @@
def lsim(system, U, T, X0=None, interp=1):
- """Simulate output of a continuous-time linear system.
+ """
+ Simulate output of a continuous-time linear system.
Parameters
----------
system : an instance of the LTI class or a tuple describing the system.
The following gives the number of elements in the tuple and
- the interpretation.
- 2 (num, den)
- 3 (zeros, poles, gain)
- 4 (A, B, C, D)
+ the interpretation:
+
+ * 2: (num, den)
+ * 3: (zeros, poles, gain)
+ * 4: (A, B, C, D)
+
U : array_like
An input array describing the input at each time `T`
(interpolation is assumed between given times). If there are
Modified: trunk/scipy/signal/signaltools.py
===================================================================
--- trunk/scipy/signal/signaltools.py 2010-05-24 13:11:58 UTC (rev 6409)
+++ trunk/scipy/signal/signaltools.py 2010-05-24 13:12:19 UTC (rev 6410)
@@ -56,13 +56,14 @@
def correlate(in1, in2, mode='full', old_behavior=True):
- """Cross-correlate two N-dimensional arrays.
+ """
+ Cross-correlate two N-dimensional arrays.
Cross-correlate in1 and in2 with the output size determined by the mode
argument.
- Arguments
- ---------
+ Parameters
+ ----------
in1: array
first input.
in2: array
@@ -88,12 +89,13 @@
an N-dimensional array containing a subset of the discrete linear
cross-correlation of in1 with in2.
- Note
- ----
+ Notes
+ -----
The correlation z of two arrays x and y of rank d is defined as
- z[...,k,...] = sum[..., i_l, ...]
+ z[...,k,...] = sum[..., i_l, ...]
x[..., i_l,...] * conj(y[..., i_l + k,...])
+
"""
val = _valfrommode(mode)
@@ -176,30 +178,36 @@
def convolve(in1, in2, mode='full', old_behavior=True):
- """Convolve two N-dimensional arrays.
+ """
+ Convolve two N-dimensional arrays.
Convolve in1 and in2 with output size determined by mode.
- Arguments
- ---------
+ Parameters
+ ----------
in1: array
first input.
in2: array
second input. Should have the same number of dimensions as in1.
mode: str {'valid', 'same', 'full'}
a string indicating the size of the output:
- - 'valid': the output consists only of those elements that do not
- rely on the zero-padding.
- - 'same': the output is the same size as the largest input centered
- with respect to the 'full' output.
- - 'full': the output is the full discrete linear cross-correlation
- of the inputs. (Default)
+ ``valid`` : the output consists only of those elements that do not
+ rely on the zero-padding.
+
+ ``same`` : the output is the same size as the largest input centered
+ with respect to the 'full' output.
+
+ ``full`` : the output is the full discrete linear cross-correlation
+ of the inputs. (Default)
+
+
Returns
-------
out: array
an N-dimensional array containing a subset of the discrete linear
cross-correlation of in1 with in2.
+
"""
volume = asarray(in1)
kernel = asarray(in2)
@@ -233,30 +241,31 @@
return correlate(volume, kernel[slice_obj], mode, old_behavior=False)
def order_filter(a, domain, rank):
- """Perform an order filter on an N-dimensional array.
+ """
+ Perform an order filter on an N-dimensional array.
- Description:
+ Description:
- Perform an order filter on the array in. The domain argument acts as a
- mask centered over each pixel. The non-zero elements of domain are
- used to select elements surrounding each input pixel which are placed
- in a list. The list is sorted, and the output for that pixel is the
- element corresponding to rank in the sorted list.
+ Perform an order filter on the array in. The domain argument acts as a
+ mask centered over each pixel. The non-zero elements of domain are
+ used to select elements surrounding each input pixel which are placed
+ in a list. The list is sorted, and the output for that pixel is the
+ element corresponding to rank in the sorted list.
- Inputs:
+ Parameters
+ ----------
+ in -- an N-dimensional input array.
+ domain -- a mask array with the same number of dimensions as in. Each
+ dimension should have an odd number of elements.
+ rank -- an non-negative integer which selects the element from the
+ sorted list (0 corresponds to the largest element, 1 is the
+ next largest element, etc.)
- in -- an N-dimensional input array.
- domain -- a mask array with the same number of dimensions as in. Each
- dimension should have an odd number of elements.
- rank -- an non-negative integer which selects the element from the
- sorted list (0 corresponds to the largest element, 1 is the
- next largest element, etc.)
+ Returns
+ -------
+ out -- the results of the order filter in an array with the same
+ shape as in.
- Output: (out,)
-
- out -- the results of the order filter in an array with the same
- shape as in.
-
"""
domain = asarray(domain)
size = domain.shape
@@ -728,12 +737,27 @@
return x
def hilbert2(x,N=None):
- """Compute the '2-D' analytic signal of `x` of length `N`.
+ """
+ Compute the '2-D' analytic signal of `x`
- See also
- --------
- hilbert
+ Parameters
+ ----------
+ x : array_like
+ 2-D signal data.
+ N : int, optional
+ Number of Fourier components. Default is ``x.shape``
+
+ Returns
+ -------
+ xa : ndarray
+ Analytic signal of `x` taken along axes (0,1).
+
+ References
+ ----------
+ .. [1] Wikipedia, "Analytic signal",
+ http://en.wikipedia.org/wiki/Analytic_signal
+
"""
x = asarray(x)
x = asarray(x)
Modified: trunk/scipy/signal/waveforms.py
===================================================================
--- trunk/scipy/signal/waveforms.py 2010-05-24 13:11:58 UTC (rev 6409)
+++ trunk/scipy/signal/waveforms.py 2010-05-24 13:12:19 UTC (rev 6410)
@@ -9,11 +9,31 @@
exp, cos, sin, polyval, polyint
def sawtooth(t,width=1):
- """Returns a periodic sawtooth waveform with period 2*pi
- which rises from -1 to 1 on the interval 0 to width*2*pi
- and drops from 1 to -1 on the interval width*2*pi to 2*pi
- width must be in the interval [0,1]
+ """
+ Return a periodic sawtooth waveform.
+ The sawtooth waveform has a period 2*pi, rises from -1 to 1 on the
+ interval 0 to width*2*pi and drops from 1 to -1 on the interval
+ width*2*pi to 2*pi. `width` must be in the interval [0,1].
+
+ Parameters
+ ----------
+ t : array_like
+ Time.
+ width : float, optional
+ Width of the waveform. Default is 1.
+
+ Returns
+ -------
+ y : ndarray
+ Output array containing the sawtooth waveform.
+
+ Examples
+ --------
+ >>> import matplotlib.pyplot as plt
+ >>> x = np.linspace(0, 20*np.pi, 500)
+ >>> plt.plot(x, sp.signal.sawtooth(x))
+
"""
t,w = asarray(t), asarray(width)
w = asarray(w + (t-t))
@@ -49,10 +69,24 @@
def square(t,duty=0.5):
- """Returns a periodic square-wave waveform with period 2*pi
- which is +1 from 0 to 2*pi*duty and -1 from 2*pi*duty to 2*pi
- duty must be in the interval [0,1]
+ """
+ Return a periodic square-wave waveform.
+ The square wave has a period 2*pi, has value +1 from 0 to 2*pi*duty
+ and -1 from 2*pi*duty to 2*pi. `duty` must be in the interval [0,1].
+
+ Parameters
+ ----------
+ t : array_like
+ The input time array.
+ duty : float, optional
+ Duty cycle.
+
+ Returns
+ -------
+ y : array_like
+ The output square wave.
+
"""
t,w = asarray(t), asarray(duty)
w = asarray(w + (t-t))
@@ -87,24 +121,33 @@
return y
def gausspulse(t,fc=1000,bw=0.5,bwr=-6,tpr=-60,retquad=0,retenv=0):
- """Return a gaussian modulated sinusoid: exp(-a t^2) exp(1j*2*pi*fc)
+ """
+ Return a gaussian modulated sinusoid: exp(-a t^2) exp(1j*2*pi*fc).
- If retquad is non-zero, then return the real and imaginary parts
- (inphase and quadrature)
- If retenv is non-zero, then return the envelope (unmodulated signal).
+ If `retquad` is non-zero, then return the real and imaginary parts
+ (in-phase and quadrature)
+ If `retenv` is non-zero, then return the envelope (unmodulated signal).
Otherwise, return the real part of the modulated sinusoid.
- Inputs:
+ Parameters
+ ----------
+ t : ndarray
+ Input array.
+ fc : int, optional
+ Center frequency (Hz).
+ bw : float, optional
+ Fractional bandwidth in frequency domain of pulse (Hz).
+ bwr: float, optional
+ Reference level at which fractional bandwidth is calculated (dB).
+ tpr : float, optional
+ If `t` is 'cutoff', then the function returns the cutoff
+ time for when the pulse amplitude falls below `tpr` (in dB).
+ retquad : int, optional
+ Return the quadrature (imaginary) as well as the real part
+ of the signal.
+ retenv : int, optional
+ Return the envelope of the signal.
- t -- Input array.
- fc -- Center frequency (Hz).
- bw -- Fractional bandwidth in frequency domain of pulse (Hz).
- bwr -- Reference level at which fractional bandwidth is calculated (dB).
- tpr -- If t is 'cutoff', then the function returns the cutoff time for when the
- pulse amplitude falls below tpr (in dB).
- retquad -- Return the quadrature (imaginary) as well as the real part of the signal
- retenv -- Return the envelope of th signal.
-
"""
if fc < 0:
raise ValueError, "Center frequency (fc=%.2f) must be >=0." % fc
Modified: trunk/scipy/signal/wavelets.py
===================================================================
--- trunk/scipy/signal/wavelets.py 2010-05-24 13:11:58 UTC (rev 6409)
+++ trunk/scipy/signal/wavelets.py 2010-05-24 13:12:19 UTC (rev 6410)
@@ -6,9 +6,17 @@
from scipy import linspace, pi, exp
def daub(p):
- """The coefficients for the FIR low-pass filter producing Daubechies wavelets.
+ """
+ The coefficients for the FIR low-pass filter producing Daubechies wavelets.
- p>=1 gives the order of the zero at f=1/2. There are 2p filter coefficients.
+ p>=1 gives the order of the zero at f=1/2.
+ There are 2p filter coefficients.
+
+ Parameters
+ ----------
+ p : int
+ Order of the zero at f=1/2, can have values from 1 to 34.
+
"""
sqrt = np.sqrt
assert(p>=1)
@@ -170,7 +178,8 @@
return x, phi, psi
def morlet(M, w=5.0, s=1.0, complete=True):
- """Complex Morlet wavelet.
+ """
+ Complex Morlet wavelet.
Parameters
----------
@@ -183,8 +192,8 @@
complete : bool
Whether to use the complete or the standard version.
- Notes:
- ------
+ Notes
+ -----
The standard version:
pi**-0.25 * exp(1j*w*x) * exp(-0.5*(x**2))
More information about the Scipy-svn
mailing list