Coverage for /usr/lib/python3/dist-packages/scipy/signal/signaltools.py : 16%

# Author: Travis Oliphant 

# 1999 -- 2002 

from __future__ import division, print_function, absolute_import 

import operator 

import threading 

import sys 

import timeit 

from . import sigtools, dlti 

from ._upfirdn import upfirdn, _output_len 

from scipy._lib.six import callable 

from scipy._lib._version import NumpyVersion 

from scipy import fftpack, linalg 

from numpy import (allclose, angle, arange, argsort, array, asarray, 

atleast_1d, atleast_2d, cast, dot, exp, expand_dims, 

iscomplexobj, mean, ndarray, newaxis, ones, pi, 

poly, polyadd, polyder, polydiv, polymul, polysub, polyval, 

product, r_, ravel, real_if_close, reshape, 

roots, sort, take, transpose, unique, where, zeros, 

zeros_like) 

import numpy as np 

import math 

from scipy.special import factorial 

from .windows import get_window 

from ._arraytools import axis_slice, axis_reverse, odd_ext, even_ext, const_ext 

from .filter_design import cheby1, _validate_sos 

from .fir_filter_design import firwin 

if sys.version_info.major >= 3 and sys.version_info.minor >= 5: 

from math import gcd 

else: 

from fractions import gcd 

__all__ = ['correlate', 'fftconvolve', 'convolve', 'convolve2d', 'correlate2d', 

'order_filter', 'medfilt', 'medfilt2d', 'wiener', 'lfilter', 

'lfiltic', 'sosfilt', 'deconvolve', 'hilbert', 'hilbert2', 

'cmplx_sort', 'unique_roots', 'invres', 'invresz', 'residue', 

'residuez', 'resample', 'resample_poly', 'detrend', 

'lfilter_zi', 'sosfilt_zi', 'sosfiltfilt', 'choose_conv_method', 

'filtfilt', 'decimate', 'vectorstrength'] 

_modedict = {'valid': 0, 'same': 1, 'full': 2} 

_boundarydict = {'fill': 0, 'pad': 0, 'wrap': 2, 'circular': 2, 'symm': 1, 

'symmetric': 1, 'reflect': 4} 

_rfft_mt_safe = (NumpyVersion(np.__version__) >= '1.9.0.dev-e24486e') 

_rfft_lock = threading.Lock() 

def _valfrommode(mode): 

try: 

return _modedict[mode] 

except KeyError: 

raise ValueError("Acceptable mode flags are 'valid'," 

" 'same', or 'full'.") 

def _bvalfromboundary(boundary): 

try: 

return _boundarydict[boundary] << 2 

except KeyError: 

raise ValueError("Acceptable boundary flags are 'fill', 'circular' " 

"(or 'wrap'), and 'symmetric' (or 'symm').") 

def _inputs_swap_needed(mode, shape1, shape2): 

""" 

If in 'valid' mode, returns whether or not the input arrays need to be 

swapped depending on whether `shape1` is at least as large as `shape2` in 

every dimension. 

This is important for some of the correlation and convolution 

implementations in this module, where the larger array input needs to come 

before the smaller array input when operating in this mode. 

Note that if the mode provided is not 'valid', False is immediately 

returned. 

""" 

if mode == 'valid': 

ok1, ok2 = True, True 

for d1, d2 in zip(shape1, shape2): 

if not d1 >= d2: 

ok1 = False 

if not d2 >= d1: 

ok2 = False 

if not (ok1 or ok2): 

raise ValueError("For 'valid' mode, one must be at least " 

"as large as the other in every dimension") 

return not ok1 

return False 

def correlate(in1, in2, mode='full', method='auto'): 

r""" 

Cross-correlate two N-dimensional arrays. 

Cross-correlate `in1` and `in2`, with the output size determined by the 

`mode` argument. 

Parameters 

---------- 

in1 : array_like 

First input. 

in2 : array_like 

Second input. Should have the same number of dimensions as `in1`. 

mode : str {'full', 'valid', 'same'}, optional 

A string indicating the size of the 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. In 'valid' mode, either `in1` or `in2` 

must be at least as large as the other in every dimension. 

``same`` 

The output is the same size as `in1`, centered 

with respect to the 'full' output. 

method : str {'auto', 'direct', 'fft'}, optional 

A string indicating which method to use to calculate the correlation. 

``direct`` 

The correlation is determined directly from sums, the definition of 

correlation. 

``fft`` 

The Fast Fourier Transform is used to perform the correlation more 

quickly (only available for numerical arrays.) 

``auto`` 

Automatically chooses direct or Fourier method based on an estimate 

of which is faster (default). See `convolve` Notes for more detail. 

.. versionadded:: 0.19.0 

Returns 

------- 

correlate : array 

An N-dimensional array containing a subset of the discrete linear 

cross-correlation of `in1` with `in2`. 

See Also 

-------- 

choose_conv_method : contains more documentation on `method`. 

Notes 

----- 

The correlation z of two d-dimensional arrays x and y is defined as:: 

z[...,k,...] = sum[..., i_l, ...] x[..., i_l,...] * conj(y[..., i_l - k,...]) 

This way, if x and y are 1-D arrays and ``z = correlate(x, y, 'full')`` 

then 

.. math:: 

z[k] = (x * y)(k - N + 1) 

= \sum_{l=0}^{||x||-1}x_l y_{l-k+N-1}^{*} 

for :math:`k = 0, 1, ..., ||x|| + ||y|| - 2` 

where :math:`||x||` is the length of ``x``, :math:`N = \max(||x||,||y||)`, 

and :math:`y_m` is 0 when m is outside the range of y. 

``method='fft'`` only works for numerical arrays as it relies on 

`fftconvolve`. In certain cases (i.e., arrays of objects or when 

rounding integers can lose precision), ``method='direct'`` is always used. 

Examples 

-------- 

Implement a matched filter using cross-correlation, to recover a signal 

that has passed through a noisy channel. 

>>> from scipy import signal 

>>> sig = np.repeat([0., 1., 1., 0., 1., 0., 0., 1.], 128) 

>>> sig_noise = sig + np.random.randn(len(sig)) 

>>> corr = signal.correlate(sig_noise, np.ones(128), mode='same') / 128 

>>> import matplotlib.pyplot as plt 

>>> clock = np.arange(64, len(sig), 128) 

>>> fig, (ax_orig, ax_noise, ax_corr) = plt.subplots(3, 1, sharex=True) 

>>> ax_orig.plot(sig) 

>>> ax_orig.plot(clock, sig[clock], 'ro') 

>>> ax_orig.set_title('Original signal') 

>>> ax_noise.plot(sig_noise) 

>>> ax_noise.set_title('Signal with noise') 

>>> ax_corr.plot(corr) 

>>> ax_corr.plot(clock, corr[clock], 'ro') 

>>> ax_corr.axhline(0.5, ls=':') 

>>> ax_corr.set_title('Cross-correlated with rectangular pulse') 

>>> ax_orig.margins(0, 0.1) 

>>> fig.tight_layout() 

>>> fig.show() 

""" 

in1 = asarray(in1) 

in2 = asarray(in2) 

if in1.ndim == in2.ndim == 0: 

return in1 * in2.conj() 

elif in1.ndim != in2.ndim: 

raise ValueError("in1 and in2 should have the same dimensionality") 

# Don't use _valfrommode, since correlate should not accept numeric modes 

try: 

val = _modedict[mode] 

except KeyError: 

raise ValueError("Acceptable mode flags are 'valid'," 

" 'same', or 'full'.") 

# this either calls fftconvolve or this function with method=='direct'