signal.fftconvolve return a tuple including lag information

[benjaminr]

I'd be surprised if this hasn't been raised before, but I think it'd be useful to provide amethod for returning lag information alongside the FFT convolution results.

For people new to cross-correlation and the FFT convolution method, it adds an extra step of complexity that can be frustrating.

I suggest passing back a numpy array with the lag information alongside the existing output in a tuple.

[e-q]

Strictly speaking, the indices of a convolution result aren't lags, so the interpretation of the indices change whether you're interpreting the result as a convolution or a cross-correlation (having time-reversed and complex-conjugated one of the input signals).

Can you be a little more specific about the confusion/complexity that you encountered?

FWIW, the example in the fftconvolve docs shows an application of the function to perform a cross-correlation, and also that the lags are given by np.arange(-len(sig)+1,len(sig)) in the case of mode='full'.

[benjaminr]

Strictly speaking, the indices of a convolution result aren't lags, so the interpretation of the indices change whether you're interpreting the result as a convolution or a cross-correlation (having time-reversed and complex-conjugated one of the input signals).

Sure, I recognise that; I think I was just making a comparison with Matlab's xcorr which does what I'm describing.

Can you be a little more specific about the confusion/complexity that you encountered?

FWIW, the example in the fftconvolve docs shows an application of the function to perform a cross-correlation, and also that the lags are given by np.arange(-len(sig)+1,len(sig)) in the case of mode='full'.

The docs example is good, but in the case of cross-correlation, getting the delay / lag out is more involved. See below for an example - it's as you mention above.

# Ahead example
>>> x = np.random.random(1000)
>>> x_ahead = x[100:]
>>> corr = signal.fftconvolve(x, x_ahead[::-1], 'full')
>>> lag = np.argmax(corr)
>>> lag
999
# Here the lag is fairly meaningless without an additional calculation
>>> lags = np.arange(-x_ahead.size + 1, x.size)
>>> lags[lag]
100

# Behind example
>>> x = np.random.random(1000)
>>> x_behind = np.pad(x, (100,0), 'constant')
>>> corr = signal.fftconvolve(x, x_behind[::-1], 'full')
>>> lag = np.argmax(corr)
>>> lag
999
>>> lags = np.arange(-x_behind.size + 1, x.size)
>>> lags[lag]
-100

Perhaps a solution is a separate xcorr style function that wraps fftconvolve, returning a tuple of the correlation output alongside the lags as I have above.

If you're trying to understand delay in time series data, I think this makes more sense in its own function where the extra range calculation is abstracted. It could be I'm just slow to figure this stuff out and probably should read the docs more carefully, but I'm sure others hit the same thing.

[e-q]

A correlation function exists in signal.correlate At the very least, the docs for that function could have some additional notes or an example for computing the lag vector. It looks like matplotlib.pyplot.xcorr actually returns the lag vector, so there is some precedent.

Searching around also reminded me of stalled efforts to add a maxlags argument to convolution and correlation functions in SciPy and NumPy, which would also perhaps motivate returning such a vector.

Would you be interested in putting together a PR to add a keyword argument to toggle returning a tuple of the lags along with the correlation result? The usual thing to do when proposing a feature is to send something out to the Scipy-dev mailing list to get people's opinions. It can be useful to already have a PR started to point to as well.

[benjaminr]

Sure happy to have a look at this.