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

[Lars G.]

Hello,

recently the 3 user-facing functions `find_peaks`, `peak_prominences`
and `peak_widths` were added to extend SciPy's peak finding capabilities.
https://scipy.github.io/devdocs/signal.html#peak-finding
During that process the idea came up to add a section on peak finding to
the "Signal Processing" tutorial.
https://scipy.github.io/devdocs/tutorial/signal.html

I have tried a few times to come up with a first draft but each time
come away with new questions. Therefore I think it might be reasonable
to have a small discussion beforehand. Some issues / question I'd like
addressed are:

- My first impression of the existing tutorial(s) is that only the basic
concepts and math are covered with maybe one example or visualizing
plot. I think that's a good scope for a tutorial. However I feel that
this concept doesn't translate well to the topic at hand. The concepts
and math behind the 3 new functions are very simple and are already
covered in the relevant docstrings. So I'm not really sure what
additional non-duplicate content would be useful here.

- 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.

- 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.

- 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`?

- 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.

Sorry, for the wordy message and I'm in no way an expert in this topic
so please take this with a grain of salt. ;)

Best regards,
Lars