[SciPy-Dev] Documentation / tutorial for peak finding in scipy.signal

[Eric Larson]

>
> - The new functions are more like building blocks that would be part of
>
a larger processing chain (filtering, peak finding, peak measurement &
> classification). My impression is that examples would be the most useful
> here to demonstrate the workflow but would be to code and plot heavy to
> fit a tutorial.
>

How about an entry in the scipy cookbook "Signal Processing" or "Other
examples" sections?

http://scipy-cookbook.readthedocs.io/

In the SciPy tutorials area you could do some basic things if you want,
even if they overlap with what is in the docstrings a bit. Then you could
put a link there to the cookbook for a more in-depth example.

- To extend on this: one thing that is very well done in Matlab is that
> it provides examples for the usage of each parameter. A good example is
> Matlab's version of `find_peaks` itself:
> https://de.mathworks.com/help/signal/ref/findpeaks.html?
> requestedDomain=true
> I think this would be really useful for some of the options of the new
> functions. E.g. the interplay between `width` and `rel_height` comes to
> mind. That would require multiple examples which is to much for a
> docstring. At least that is my impression.
>

I see MATLAB's documentation as being roughly equivalent to our docstrings.
So if it seems like the MATLAB docs are well organized and not too long,
the same could go for our docstrings.

I don't see too much of an issue if the `find_peaks` docstring becomes a
bit longer than usual. Most of the "need it now" information is
concentrated at the top (params). The examples and notes come later, and
can be browsed (or not) as necessary by users.

- To demonstrate peak finding I would need a signal to analyze. I'm not
> sure how to generate complex demo-signals in only a few lines of code
> that don't shift the focus of the reader. The best I could come up with
> can be seen in `find_peaks` docstring. How is this usually handled?
> Would it be okay to import this stuff from `misc`?
>

We have `face` and `ascent` in `misc` already for 2D signals. I think it
would be nice to have something like this for 1D signals, assuming we can
find one that won't take up a ton of space (< 500kB maybe, since that's
what ascent takes, and `face` takes up 1.5MB?). We don't want to bloat the
repo, but a reasonable sound choice could be used in many examples.

The most popular "freesound.org" clip is a creative-commons licensed
thunderstorm
recording <https://freesound.org/people/RHumphries/sounds/2523/>, maybe
this could be made mono, truncated, and/or resampled to be sufficiently
small? Other ideas welcome.

- Should this tutorial cover peak finding with wavelet transformation as
> well? Reading the roadmap it seems like it's not decided whether wavelet
> transformation is within the scope of SciPy. So I'd think this topic
> should be left out until this is decided.
>

We can always add this later, so I'd say only include it if you're
motivated to do it.

Eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20180316/b2b47e73/attachment.html>