Skip to main content
`Ctrl`+`K`

# numpy.correlate

numpy.correlate(a, v, mode='valid')

  Cross-correlation of two 1-dimensional sequences.

  This function computes the correlation as generally defined in signal processing texts [1]:

  \[c_k = \sum_n a_{n+k} \cdot \overline{v}_n\]

  with a and v sequences being zero-padded where necessary and \(\overline v\) denoting complex conjugation.

  Parameters:
    a, v array_like

      Input sequences.

    mode{‘valid’, ‘same’, ‘full’}, optional

      Refer to the `convolve` docstring. Note that the default is ‘valid’, unlike `convolve`, which uses ‘full’.

  Returns:
    out ndarray

      Discrete cross-correlation of a and v.

  See also

  `convolve`

    Discrete, linear convolution of two one-dimensional sequences.

  `scipy.signal.correlate`

    uses FFT which has superior performance on large arrays.

  Notes

  The definition of correlation above is not unique and sometimes correlation may be defined differently. Another common definition is [1]:

  \[c'_k = \sum_n a_{n} \cdot \overline{v_{n+k}}\]

  which is related to \(c_k\) by \(c'_k = c_{-k}\).

  `numpy.correlate` may perform slowly in large arrays (i.e. n = 1e5) because it does not use the FFT to compute the convolution; in that case, scipy.signal.correlate might be preferable.

  References

  [1] (1,2)

  Wikipedia, “Cross-correlation”, https://en.wikipedia.org/wiki/Cross-correlation

  Examples

      >>> import numpy as np
      >>> np.correlate([1, 2, 3], [0, 1, 0.5])
      array([3.5])
      >>> np.correlate([1, 2, 3], [0, 1, 0.5], "same")
      array([2. ,  3.5,  3. ])
      >>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
      array([0.5,  2. ,  3.5,  3. ,  0. ])

  Using complex sequences:

      >>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full')
      array([ 0.5-0.5j,  1.0+0.j ,  1.5-1.5j,  3.0-1.j ,  0.0+0.j ])

  Note that you get the time reversed, complex conjugated result (\(\overline{c_{-k}}\)) when the two input sequences a and v change places:

      >>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
      array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j])