What is the difference between threshold and prominence in 'scipy.signal.find_peaks'?

I'm trying to find the peaks of a noisy signal using scipy.signal.find_peaks and I realised that I don't fully understand the difference between the threshold and prominence arguments.

I understand that prominence is equivalent to topographical prominence, i.e. the height of a peak relative to the surrounding terrain. However, I don't quite understand in which ways the threshold argument is different from this. From the above link both arguments seem equivalent to me. What is exactly the difference between threshold and prominence in this case?

Threshold is about vertical distance to the samples right before and after. Prominence is about vertical distance to the deepest valley.

Here's a visual explanation of the difference:

In this graph of cos(x), the peak has a threshold of 0.191, and a prominence of 2.

What implications does this have?

• Threshold is good at distinguishing peaks which go up for a single sample, then go down.
• Prominence is good at distinguishing peaks which go up and down over the course of several samples.
• A single threshold value gets more selective as the sampling rate goes up. However, prominence is independent of sampling rate. (As an example, try changing the number of samples from 21 to 41 in the example below, and see how threshold changes.)
• The parameter wlen controls how many samples are searched for the valley to determine prominence. If you set wlen=3, then prominence and threshold are the same. By default, it will search until the next larger peak. See documentation.

Code used to produce graphic

import matplotlib.pyplot as plt
import numpy as np
import scipy.signal
x = np.linspace(0, 4*np.pi, 21)
y = np.cos(x)
plt.plot(x, y)
# Show threshold and prominence for peak
print(scipy.signal.find_peaks(y, threshold=0, prominence=0))