DOC: numpy.correlate, document the resultant index mapping

[bernd-wechner]

Proposed new feature or change:

This is documented here in source:

numpy/numpy/core/numeric.py

Line 738 in d92cc2d

def convolve(a, v, mode='full'):

and here live:

https://numpy.org/doc/stable/reference/generated/numpy.convolve.html

Context

There are three modes documented, each of which produces a different length of output array.

In practical applications, this operation is often tied to other axes. The implicit one of course is simply the index, as this general convolution, rightly, makes no assumptions about the application.

And yet, because real applications abound (not uncommonly in signal processing) in which there is a tied axis (often a time measure, or a frequency) measure to the signal that is being provided to this function as a and the array v represents a filter of some sort.

In many (perhaps most, by some significant margin) such applications, the a provides the reference axis implicitly (is the signal which has an associated time - or frequency - for each sample).

The Problem (missing documentation)

In such applications it's important to the choice of mode here, to adjust (modify) any associated axis data and to do so in a 'correct' (or plausible, or useful) manner.

We can do some guess work here. same is the simplest, in which each element of the result maps one to one with each element of the longer of a and v. If we conjecture (and that is all it is at present) that many others in this application sphere and elsewhere are likely to use this method with len(a)>len(v) (quite probably much greater than), then for full we are forced into conjecture (or code analysis inside of numpy - which is why this is a request to document).

full documents an output of (N+M-1,) and which is up front which suggests possibly (or, we might imagine that) the array a and v overlap by one sample being a[0] and v[0] with a[-M:0] set to 0 and then ends with and overlap of a[N] with v[0]. The last N samples of the output then map to the samples in a with the first M-1 a boundary effect. That is what the first "Example" suggests, but I'd feel far more comfortable if it were stated explicitly (not least because it is very different to ending the process with a[-1] overlapping v[0] which would add another M-1 samples to the output or other scenarios.

valid similarly can be inferred as commencing with a[0] overlapping v[-1] and ending with a[-1] overlapping v[0] which, if a and v are close in length, produces a very short result.

The Solution

The Examples are lovely, and useful, and the sliding window imagery very commonly found in signal processing applications too. So I'd like to see some modest documentation that speaks to the mapping of the result's indices to a's indices. If my inferences here are true, I am more than willing to PR a modest change to:

numpy/numpy/core/numeric.py

Line 738 in d92cc2d

def convolve(a, v, mode='full'):

documenting that as time permits. For now, I take these conclusions as evidenced by the examples ;-).

Aside: I came across this issue and need, indeed by looking at how a particular filter changes over a series of filter and decimation steps in a signal processing application, and so decimated the time array as well, but this convolution introduced changes to the length of the signal which I need to replicate in the time array to keep matplotlib happy ;-).