Detect events or pulses in sampled data
Signal processing
SciPy · Function
signal.find_peaks
Finds local maxima in a one-dimensional signal and optionally filters them by height, spacing, prominence, width, threshold, or plateau size. It returns peak indices together with the properties calculated for the selected peaks.
How it works
find_peaks examines a one-dimensional signal for local maxima using neighboring-sample comparisons. Optional property constraints such as height, threshold, prominence, width, distance, and plateau size reduce the returned candidates; properties computed for accepted peaks are returned in a dictionary.
Syntax
scipy.signal.find_peaks(x, height=None, threshold=None, distance=None, prominence=None, width=None, wlen=None, rel_height=0.5, plateau_size=None)Parameters
| Name | Type | Description |
|---|---|---|
x | sequence | One-dimensional signal containing peaks. |
height | number or ndarray or sequence, optional | Required peak height; scalar, array, or sequence, optionally supplied as an interval. |
threshold | number or ndarray or sequence, optional | Required vertical distance from neighboring samples; scalar, array, or sequence. |
distance | number, optional | Minimum horizontal separation between neighboring peaks, in samples; must be at least 1. |
prominence | number or ndarray or sequence, optional | Required peak prominence; scalar, array, or sequence. |
width | number or ndarray or sequence, optional | Required peak width; scalar, array, or sequence. |
wlen | int, optional | Window length used when calculating prominence and width. |
rel_height | float, optional | Relative height used to calculate width. |
plateau_size | number or ndarray or sequence, optional | Required flat-top plateau size; scalar, array, or sequence. |
Returns
A tuple: the indices of detected peaks and a dictionary containing calculated peak properties.
Key points
- Input is a one-dimensional signal, and initial candidates are local maxima identified by comparing neighboring samples.
- Optional conditions let you select only the candidates matching desired peak characteristics.
- height filters peaks by their amplitude and accepts a scalar, an array, or a sequence.
- threshold requires a minimum vertical difference from neighboring samples.
- distance enforces a minimum index separation of at least one sample between retained peaks.
- prominence filters by how strongly a peak stands above its surrounding baseline.
- width filters peaks according to their measured widths.
Common mistakes
- Clean or otherwise handle NaN values first, because NaNs can lead to surprising peak detection results.
Example: Filter peaks by height and spacing
import numpy as np
from scipy.signal import find_peaks
signal = np.array([0, 1, 0, 2, 0, 1, 0])
peaks, properties = find_peaks(signal, height=1.5, distance=2)
print(peaks) # [3]
print(properties["peak_heights"]) # [2.]Finds local maxima, then keeps only peaks at least 1.5 high and separated by two samples.
When to use it
Select prominent peaks while retaining their measured properties
Scientific analysis
Identify local maxima subject to spacing and amplitude constraints
Time-series analysis
Interview questions
QHow does find_peaks define a peak?
A peak is a sample whose two direct neighbors have smaller amplitudes. The function first finds these local maxima and can then filter them using property conditions.
Follow-up: How are flat peaks handled? The central plateau index is returned, with the lower central index used when the plateau has even length.
QWhat does the distance parameter do?
distance specifies the minimum horizontal separation between neighboring retained peaks and must be at least 1 sample. If candidates conflict, smaller peaks are removed until the spacing requirement is met.
Follow-up: Does distance guarantee separation of plateau edges? No; the documented spacing applies to peak indices, while plateau edges can be closer.
QWhat does find_peaks return?
The function returns a tuple containing the indices of detected peaks and a dictionary of calculated properties. The dictionary can include heights, thresholds, prominences, widths, plateau sizes, and related boundary values when the corresponding conditions are requested.
Follow-up: How can properties be computed without excluding peaks? Supply the relevant property as the open interval (None, None).
Related
peak_prominencespeak_widthsfind_peaks_cwt