[SciPy-dev] FFT docstrings (was: Scipy Tutorial (and updating it))

[jh at physics.ucf.edu]

Tom Grydeland <tom.grydeland at gmail.com> wrote:

> I've gone on to rfft, irfft, fftn and irfftn, and I am struggling a
> bit with these, especially with the description of the length/shape
> argument.  I know perfectly well what they should tell the reader, but
> I am not 100% convinced the current prose actually tells it clearly.

Thanks for your work, Tom!  I think the text so far is fine.  I
tweaked some of the pages a little.

There's room and need for a bit more, since FFTs are among the most
used and abused methods out there.  Recall that our audience is one
level below likely users.  There's need for a short intro to the
whole concept on the module page (I added one), which each routine
page should refer to (but I haven't put those references in).

Also, the current routine examples satisfy a mathematician but do not
give insight into what the FT actually *does*, i.e., extract the
periodic content of a signal.  Also, an example should show the most
basic use, i.e., taking the modulus and the arctan of the inputs to
get the amplitude and phase of the contributing sinusoids.  Too many
people take the real part of an FFT and think they've got the
amplitude.  If you did a sine wave of amplitude 2 in 8 points, you
could show in a simple example how to pull that out of the fft.  For
the complex case, point out that you have to fold (or double) the
first half of the output, etc., since the negative frequencies get
half the signal for real inputs.  Then refer to rfft.  Note that many
users will not at first understand why (or even that) we have rfft,
since most packages do not provide it, which is why it is worth some
explanation.

Doing all this consistently across the many routines would be very
valuable.  The rfft vs. fft explanation might best belong on the
module page, since there are several routines for each.  Then the
routines themselves can have relatively spare pages.  The formulae
themselves might best go on the module page, for the same reason.

Thanks again for your contributions.  Send me your postal address and
your T-shirt size by private email and we'll send you one right away!

--jh--