# scipy/scipy

### Subversion checkout URL

You can clone with
or
.

DOC: fix more Sphinx issues.

commit 1e86a0567643f01c2b1e95236a6824a8396d1164 1 parent 0d06383
rgommers authored
28 scipy/signal/cont2discrete.py
 @@ -21,20 +21,23 @@ def cont2discrete(sys, dt, method="zoh", alpha=None): sys : 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) + + * 2: (num, den) + * 3: (zeros, poles, gain) + * 4: (A, B, C, D) dt : float The discretization time step. method : {"gbt", "bilinear", "euler", "backward_diff", "zoh"} Which method to use: + * gbt: generalized bilinear transformation * bilinear: Tustin's approximation ("gbt" with alpha=0.5) * euler: Euler (or forward differencing) method ("gbt" with alpha=0) * backward_diff: Backwards differencing ("gbt" with alpha=1.0) * zoh: zero-order hold (default). + alpha : float within [0, 1] The generalized bilinear transformation weighting parameter, which should only be specified with method="gbt", and is ignored otherwise @@ -55,15 +58,18 @@ def cont2discrete(sys, dt, method="zoh", alpha=None): may be used, which includes the common Tustin's bilinear approximation, an Euler's method technique, or a backwards differencing technique. - The Zero-Order Hold (zoh) method is based on: - http://en.wikipedia.org/wiki/Discretization#Discretization_of_linear_state_space_models + The Zero-Order Hold (zoh) method is based on [1]_, the generalized bilinear + approximation is based on [2]_ and [3]. + + References + ---------- + .. [1] http://en.wikipedia.org/wiki/Discretization#Discretization_of_linear_state_space_models + + .. [2] http://techteach.no/publications/discretetime_signals_systems/discrete.pdf - Generalize bilinear approximation is based on: - http://techteach.no/publications/discretetime_signals_systems/discrete.pdf - and - G. Zhang, X. Chen, and T. Chen, Digital redesign via the generalized bilinear - transformation, Int. J. Control, vol. 82, no. 4, pp. 741-754, 2009. - (http://www.ece.ualberta.ca/~gfzhang/research/ZCC07_preprint.pdf) + .. [3] G. Zhang, X. Chen, and T. Chen, Digital redesign via the generalized + bilinear transformation, Int. J. Control, vol. 82, no. 4, pp. 741-754, + 2009. (http://www.ece.ualberta.ca/~gfzhang/research/ZCC07_preprint.pdf) """ if len(sys) == 2:
8 scipy/signal/dltisys.py
 @@ -129,10 +129,12 @@ def dimpulse(system, x0=None, t=None, n=None): ---------- system : tuple The following gives the number of elements in the tuple and - the interpretation. + the interpretation: + * 3: (num, den, dt) * 4: (zeros, poles, gain, dt) * 5: (A, B, C, D, dt) + x0 : array_like, optional Initial state-vector. Defaults to zero. t : array_like, optional @@ -202,10 +204,12 @@ def dstep(system, x0=None, t=None, n=None): ---------- system : a tuple describing the system. The following gives the number of elements in the tuple and - the interpretation. + the interpretation: + * 3: (num, den, dt) * 4: (zeros, poles, gain, dt) * 5: (A, B, C, D, dt) + x0 : array_like, optional Initial state-vector (default is zero). t : array_like, optional
27 scipy/signal/fir_filter_design.py
 @@ -178,11 +178,12 @@ def firwin(numtaps, cutoff, width=None, window='hamming', pass_zero=True, Set to True to scale the coefficients so that the frequency response is exactly unity at a certain frequency. That frequency is either: - 0 (DC) if the first passband starts at 0 (i.e. pass_zero - is True); - `nyq` (the Nyquist rate) if the first passband ends at - `nyq` (i.e the filter is a single band highpass filter); - center of first passband otherwise. + + - 0 (DC) if the first passband starts at 0 (i.e. pass_zero + is True); + - `nyq` (the Nyquist rate) if the first passband ends at + `nyq` (i.e the filter is a single band highpass filter); + center of first passband otherwise. nyq : float Nyquist frequency. Each frequency in `cutoff` must be between 0 @@ -190,7 +191,7 @@ def firwin(numtaps, cutoff, width=None, window='hamming', pass_zero=True, Returns ------- - h : 1D ndarray + h : 1-D ndarray Coefficients of length `numtaps` FIR filter. Raises @@ -322,45 +323,39 @@ def firwin2(numtaps, freq, gain, nfreqs=None, window='hamming', nyq=1.0, antisym numtaps : int The number of taps in the FIR filter. `numtaps` must be less than `nfreqs`. - freq : array-like, 1D The frequency sampling points. Typically 0.0 to 1.0 with 1.0 being Nyquist. The Nyquist frequency can be redefined with the argument `nyq`. - The values in `freq` must be nondecreasing. A value can be repeated once to implement a discontinuity. The first value in `freq` must be 0, and the last value must be `nyq`. - gain : array-like The filter gains at the frequency sampling points. Certain constraints to gain values, depending on the filter type, are applied, see Notes for details. - nfreqs : int, optional The size of the interpolation mesh used to construct the filter. For most efficient behavior, this should be a power of 2 plus 1 (e.g, 129, 257, etc). The default is one more than the smallest power of 2 that is not less than `numtaps`. `nfreqs` must be greater than `numtaps`. - window : string or (string, float) or float, or None, optional Window function to use. Default is "hamming". See `scipy.signal.get_window` for the complete list of possible values. If None, no window function is applied. - nyq : float Nyquist frequency. Each frequency in `freq` must be between 0 and `nyq` (inclusive). - antisymmetric : bool Flag setting wither resulting impulse responce is symmetric/antisymmetric. See Notes for more details. Returns ------- - taps : numpy 1D array of length `numtaps` - The filter coefficients of the FIR filter. + taps : ndarray + The filter coefficients of the FIR filter, as a 1-D array of length + `numtaps`. Examples -------- @@ -387,6 +382,7 @@ def firwin2(numtaps, freq, gain, nfreqs=None, window='hamming', nyq=1.0, antisym The FIR filter will have linear phase. The type of filter is determined by the value of 'numtaps` and `antisymmetric` flag. There are four possible combinations: + - odd `numtaps`, `antisymmetric` is False, type I filter is produced - even `numtaps`, `antisymmetric` is False, type II filter is produced - odd `numtaps`, `antisymmetric` is True, type III filter is produced @@ -394,6 +390,7 @@ def firwin2(numtaps, freq, gain, nfreqs=None, window='hamming', nyq=1.0, antisym Magnitude response of all but type I filters are subjects to following constraints: + - type II -- zero at the Nyquist frequency - type III -- zero at zero and Nyquist frequencies - type IV -- zero at zero frequency
47 scipy/signal/ltisys.py
 @@ -226,10 +226,13 @@ class lti(object): """Linear Time Invariant class which simplifies representation. """ def __init__(self, *args, **kwords): - """Initialize the LTI system using either: - (numerator, denominator) - (zeros, poles, gain) - (A, B, C, D) -- state-space. + """ + Initialize the LTI system using either: + + - (numerator, denominator) + - (zeros, poles, gain) + - (A, B, C, D) : state-space. + """ N = len(args) if N == 2: # Numerator denominator transfer function input @@ -604,9 +607,11 @@ def impulse2(system, X0=None, T=None, N=None, **kwargs): 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) + + * 2 (num, den) + * 3 (zeros, poles, gain) + * 4 (A, B, C, D) + T : 1-D array_like, optional The time steps at which the input is defined and at which the output is desired. If `T` is not given, the function will @@ -682,10 +687,12 @@ def step(system, X0=None, T=None, N=None): ---------- 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) + X0 : array_like, optional Initial state-vector (default is zero). T : array_like, optional @@ -703,6 +710,7 @@ def step(system, X0=None, T=None, N=None): See also -------- scipy.signal.step2 + """ if isinstance(system, lti): sys = system @@ -728,22 +736,23 @@ def step2(system, X0=None, T=None, N=None, **kwargs): ---------- 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) + X0 : array_like, optional Initial state-vector (default is zero). T : array_like, optional Time points (computed if not given). N : int Number of time points to compute if `T` is not given. - **kwargs : + kwargs : Additional keyword arguments are passed on the function `scipy.signal.lsim2`, which in turn passes them on to - :func:`scipy.integrate.odeint`. See the documentation for - :func:`scipy.integrate.odeint` for information about these - arguments. + `scipy.integrate.odeint`. See the documentation for + `scipy.integrate.odeint` for information about these arguments. Returns -------
71 scipy/signal/signaltools.py
 @@ -65,14 +65,15 @@ def correlate(in1, in2, mode='full'): 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: + mode: str {'valid', 'same', 'full'}, optional + A string indicating the size of the output: + - 'valid': the output consists only of those elements that do not - rely on the zero-padding. + rely on the zero-padding. - 'same': the output is the same size as ``in1`` centered with respect to the 'full' output. - 'full': the output is the full discrete linear cross-correlation - of the inputs. (Default) + of the inputs (default). Returns ------- @@ -82,7 +83,7 @@ def correlate(in1, in2, mode='full'): Notes ----- - The correlation z of two arrays x and y of rank d is defined as + The correlation z of two arrays x and y of rank d is defined as:: z[...,k,...] = sum[..., i_l, ...] x[..., i_l,...] * conj(y[..., i_l + k,...]) @@ -855,22 +856,22 @@ def unique_roots(p, tol=1e-3, rtype='min'): def invres(r, p, k, tol=1e-3, rtype='avg'): """Compute b(s) and a(s) from partial fraction expansion: r,p,k - If M = len(b) and N = len(a) + If ``M = len(b)`` and ``N = len(a)``:: - b(s) b[0] x**(M-1) + b[1] x**(M-2) + ... + b[M-1] - H(s) = ------ = ---------------------------------------------- - a(s) a[0] x**(N-1) + a[1] x**(N-2) + ... + a[N-1] + b(s) b[0] x**(M-1) + b[1] x**(M-2) + ... + b[M-1] + H(s) = ------ = ---------------------------------------------- + a(s) a[0] x**(N-1) + a[1] x**(N-2) + ... + a[N-1] - r[0] r[1] r[-1] - = -------- + -------- + ... + --------- + k(s) - (s-p[0]) (s-p[1]) (s-p[-1]) + r[0] r[1] r[-1] + = -------- + -------- + ... + --------- + k(s) + (s-p[0]) (s-p[1]) (s-p[-1]) If there are any repeated roots (closer than tol), then the partial - fraction expansion has terms like + fraction expansion has terms like:: - r[i] r[i+1] r[i+n-1] - -------- + ----------- + ... + ----------- - (s-p[i]) (s-p[i])**2 (s-p[i])**n + r[i] r[i+1] r[i+n-1] + -------- + ----------- + ... + ----------- + (s-p[i]) (s-p[i])**2 (s-p[i])**n See Also -------- @@ -981,22 +982,22 @@ def residue(b, a, tol=1e-3, rtype='avg'): def residuez(b, a, tol=1e-3, rtype='avg'): """Compute partial-fraction expansion of b(z) / a(z). - If M = len(b) and N = len(a) + If ``M = len(b)`` and ``N = len(a)``:: - b(z) b[0] + b[1] z**(-1) + ... + b[M-1] z**(-M+1) - H(z) = ------ = ---------------------------------------------- - a(z) a[0] + a[1] z**(-1) + ... + a[N-1] z**(-N+1) + b(z) b[0] + b[1] z**(-1) + ... + b[M-1] z**(-M+1) + H(z) = ------ = ---------------------------------------------- + a(z) a[0] + a[1] z**(-1) + ... + a[N-1] z**(-N+1) r[0] r[-1] = --------------- + ... + ---------------- + k[0] + k[1]z**(-1) ... (1-p[0]z**(-1)) (1-p[-1]z**(-1)) If there are any repeated roots (closer than tol), then the partial - fraction expansion has terms like + fraction expansion has terms like:: - r[i] r[i+1] r[i+n-1] - -------------- + ------------------ + ... + ------------------ - (1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(-1))**n + r[i] r[i+1] r[i+n-1] + -------------- + ------------------ + ... + ------------------ + (1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(-1))**n See also -------- @@ -1051,22 +1052,22 @@ def residuez(b, a, tol=1e-3, rtype='avg'): def invresz(r, p, k, tol=1e-3, rtype='avg'): """Compute b(z) and a(z) from partial fraction expansion: r,p,k - If M = len(b) and N = len(a) + If ``M = len(b)`` and ``N = len(a)``:: - b(z) b[0] + b[1] z**(-1) + ... + b[M-1] z**(-M+1) - H(z) = ------ = ---------------------------------------------- - a(z) a[0] + a[1] z**(-1) + ... + a[N-1] z**(-N+1) + b(z) b[0] + b[1] z**(-1) + ... + b[M-1] z**(-M+1) + H(z) = ------ = ---------------------------------------------- + a(z) a[0] + a[1] z**(-1) + ... + a[N-1] z**(-N+1) - r[0] r[-1] - = --------------- + ... + ---------------- + k[0] + k[1]z**(-1) ... - (1-p[0]z**(-1)) (1-p[-1]z**(-1)) + r[0] r[-1] + = --------------- + ... + ---------------- + k[0] + k[1]z**(-1) ... + (1-p[0]z**(-1)) (1-p[-1]z**(-1)) If there are any repeated roots (closer than tol), then the partial - fraction expansion has terms like + fraction expansion has terms like:: - r[i] r[i+1] r[i+n-1] - -------------- + ------------------ + ... + ------------------ - (1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(-1))**n + r[i] r[i+1] r[i+n-1] + -------------- + ------------------ + ... + ------------------ + (1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(-1))**n See also --------
62 scipy/signal/splinemodule.c
 @@ -260,12 +260,10 @@ static PyObject *FIRsepsym2d(PyObject *NPY_UNUSED(dummy), PyObject *args) static char doc_IIRsymorder1[] = " symiirorder1(input, c0, z1 {, precision}) -> output\n" "\n" -" Description:\n" -"\n" " Implement a smoothing IIR filter with mirror-symmetric boundary conditions\n" " using a cascade of first-order sections. The second section uses a\n" " reversed sequence. This implements a system with the following\n" -" transfer function and mirror-symmetric boundary conditions.\n" +" transfer function and mirror-symmetric boundary conditions::\n" "\n" " c0 \n" " H(z) = --------------------- \n" @@ -273,16 +271,20 @@ static char doc_IIRsymorder1[] = " symiirorder1(input, c0, z1 {, precision}) -> "\n" " The resulting signal will have mirror symmetric boundary conditions as well.\n" "\n" -" Inputs:\n" -"\n" -" input -- the input signal.\n" -" c0, z1 -- parameters in the transfer function.\n" -" precision -- specifies the precision for calculating initial conditions\n" -" of the recursive filter based on mirror-symmetric input.\n" +" Parameters\n" +" ----------\n" +" input : ndarray\n" +" The input signal.\n" +" c0, z1 : scalar\n" +" Parameters in the transfer function.\n" +" precision :\n" +" Specifies the precision for calculating initial conditions\n" +" of the recursive filter based on mirror-symmetric input.\n" "\n" -" Output:\n" -"\n" -" output -- filtered signal."; +" Returns\n" +" -------\n" +" output : ndarray\n" +" The filtered signal."; static PyObject *IIRsymorder1(PyObject *NPY_UNUSED(dummy), PyObject *args) { @@ -379,30 +381,34 @@ static PyObject *IIRsymorder1(PyObject *NPY_UNUSED(dummy), PyObject *args) static char doc_IIRsymorder2[] = " symiirorder2(input, r, omega {, precision}) -> output\n" "\n" -" Description:\n" -"\n" " Implement a smoothing IIR filter with mirror-symmetric boundary conditions\n" " using a cascade of second-order sections. The second section uses a\n" -" reversed sequence. This implements the following transfer function:\n" +" reversed sequence. This implements the following transfer function::\n" +"\n" +" cs^2\n" +" H(z) = ---------------------------------------\n" +" (1 - a2/z - a3/z^2) (1 - a2 z - a3 z^2 )\n" "\n" -" cs^2\n" -" H(z) = ---------------------------------------\n" -" (1 - a2/z - a3/z^2) (1 - a2 z - a3 z^2 )\n" +" where::\n" "\n" -" where a2 = (2 r cos omega)\n" +" a2 = (2 r cos omega)\n" " a3 = - r^2\n" " cs = 1 - 2 r cos omega + r^2\n" "\n" -" Inputs:\n" -"\n" -" input -- the input signal.\n" -" r, omega -- parameters in the transfer function.\n" -" precision -- specifies the precision for calculating initial conditions\n" -" of the recursive filter based on mirror-symmetric input.\n" -"\n" -" Output:\n" +" Parameters\n" +" ----------\n" +" input : ndarray\n" +" The input signal.\n" +" r, omega : scalar\n" +" Parameters in the transfer function.\n" +" precision :\n" +" Specifies the precision for calculating initial conditions\n" +" of the recursive filter based on mirror-symmetric input.\n" "\n" -" output -- filtered signal.\n"; +" Returns\n" +" -------\n" +" output : ndarray\n" +" The filtered signal."; static PyObject *IIRsymorder2(PyObject *NPY_UNUSED(dummy), PyObject *args) {
22 scipy/signal/wavelets.py
 @@ -86,7 +86,7 @@ def wavedec(amn, hk): def cascade(hk, J=7): """ - Return (x, phi, psi) at dyadic points K/2**J from filter coefficients. + Return (x, phi, psi) at dyadic points ``K/2**J`` from filter coefficients. Parameters ---------- @@ -97,18 +97,18 @@ def cascade(hk, J=7): Returns ------- - x : - The dyadic points K/2**J for ``K=0...N * (2**J)-1`` where - ``len(hk) = len(gk) = N+1`` - phi : - The scaling function ``phi(x)`` at `x`: + x : ndarray + The dyadic points ``K/2**J`` for ``K=0...N * (2**J)-1`` where + ``len(hk) = len(gk) = N+1``. + phi : ndarray + The scaling function ``phi(x)`` at `x`:: N phi(x) = sum hk * phi(2x-k) k=0 - psi : - The wavelet function ``psi(x)`` at `x`: + psi : ndarray, optional + The wavelet function ``psi(x)`` at `x`:: N phi(x) = sum gk * phi(2x-k) @@ -304,8 +304,8 @@ def cwt(data, wavelet, widths): Wavelet function, which should take 2 arguments. The first argument is a width parameter, defining the size of the wavelet (e.g. standard deviation of a gaussian). - The second is the number of points that the returned vector will have - (len(wavelet(width,length)) == length). See `ricker`, which + The second is the number of points that the returned vector will have + (len(wavelet(width,length)) == length). See `ricker`, which satisfies these requirements. widths : sequence Widths to use for transform. @@ -318,7 +318,7 @@ def cwt(data, wavelet, widths): Notes ------ cwt[ii,:] = scipy.signal.convolve(data,wavelet(width[ii], length), mode='same') - where length = min(10 * width[ii], len(data)). + where length = min(10 * width[ii], len(data)). Examples --------
94 scipy/spatial/kdtree.py
 @@ -361,9 +361,9 @@ def query(self, x, k=1, eps=0, p=2, distance_upper_bound=np.inf): Examples -------- - >>> from scipy.spatial import KDTree + >>> from scipy import spatial >>> x, y = np.mgrid[0:5, 2:8] - >>> tree = KDTree(zip(x.ravel(), y.ravel())) + >>> tree = spatial.KDTree(zip(x.ravel(), y.ravel())) >>> tree.data array([[0, 2], [0, 3], @@ -540,25 +540,26 @@ def query_ball_tree(self, other, r, p=2., eps=0): """Find all pairs of points whose distance is at most r Parameters - ========== - - other : KDTree - The tree containing points to search against - r : positive float - The maximum distance - p : float 1<=p<=infinity - Which Minkowski norm to use - eps : nonnegative float - Approximate search. Branches of the tree are not explored - if their nearest points are further than r/(1+eps), and branches - are added in bulk if their furthest points are nearer than r*(1+eps). + ---------- + other : KDTree instance + The tree containing points to search against. + r : float + The maximum distance, has to be positive. + p : float, optional + Which Minkowski norm to use. `p` has to meet the condition + ``1 <= p <= infinity``. + eps : float, optional + Approximate search. Branches of the tree are not explored + if their nearest points are further than ``r/(1+eps)``, and + branches are added in bulk if their furthest points are nearer + than ``r * (1+eps)``. `eps` has to be non-negative. Returns - ======= - + ------- results : list of lists - For each element self.data[i] of this tree, results[i] is a list of the - indices of its neighbors in other.data. + For each element ``self.data[i]`` of this tree, ``results[i]`` is a + list of the indices of its neighbors in ``other.data``. + """ results = [[] for i in range(self.n)] def traverse_checking(node1, rect1, node2, rect2): @@ -604,26 +605,26 @@ def traverse_no_checking(node1, node2): return results def query_pairs(self, r, p=2., eps=0): - """Find all pairs of points whose distance is at most r + """Find all pairs of points whose distance is at most r. Parameters - ========== - + ---------- r : positive float - The maximum distance - p : float 1<=p<=infinity - Which Minkowski norm to use - eps : nonnegative float - Approximate search. Branches of the tree are not explored + The maximum distance. + p : float, optional + Which Minkowski norm to use. `p` has to meet the condition + ``1 <= p <= infinity``. + eps : float, optional + Approximate search. Branches of the tree are not explored if their nearest points are further than r/(1+eps), and branches - are added in bulk if their furthest points are nearer than r*(1+eps). + are added in bulk if their furthest points are nearer than + ``r * (1+eps)``. `eps` has to be non-negative. Returns - ======= - + ------- results : set - set of pairs (i,j), i