out keyword for spectrogram

[v923z]

One of the most often called functions is utils.spectrogram, which calculates the Fourier spectrum of the input signal. The function allocates memory for its output on each call. The question I'd like to raise here, is whether it would make sense to add the out keyword to the function (this is not a numpy function, therefore, compliance with numpy standards is not an issue here), and if so, how should that happen.

One conceptual problem is that spectrogram returns the spectrum, i.e., the output will be a real array with the same length as the input. However, the calculation of the Fourier transform internally requires twice as many real numbers, or the same number of complex numbers.

One option would be to place the output in the first half of out, and implement something like this

sample_length = 1024
out = np.zeros(2 * sample_length, dtype=np.float)

utils.spectrogram(samples, out=out)

# do something with out[:sample_length] 

Another possibility is to implement spectrogram as a method of a class that keeps track of the number of sample points, or we could add a helper function like

out = utils.reserve_spectrogram_out(samples)
utils.spectrogram(samples, out=out)

# do something with out[:sample_length] 

Any thoughts or suggestions? @jepler @dhalbert @jimmo