Peak Detection

Shipping

peak_detection

Local maxima/minima with prominence, threshold, and min_distance filtering

Signature

Inputs

signalSignalrequired

Outputs

peaksSignal
valleysSignal
peakCountScalar

Parameters

Key	Type	Default
`threshold`	float	0.0
`min_distance`	int	1
`prominence`	float	0.0

Description

Peak Detection locates local extrema in a 1-D signal and reports them, applying three cascaded filters: an absolute amplitude threshold, a minimum sample spacing min_distance, and topographic prominence. A sample $x_{i}$ is a candidate peak when it is strictly greater than its immediate neighbors ( $x_{i} > x_{i - 1}$ and $x_{i} > x_{i + 1}$ ); valleys are detected symmetrically as local minima.

The node emits three outputs. `peaks` and `valleys` carry the detected extrema (preserving the amplitude values and their sample positions/timestamps from the input), and `peakCount` is a scalar giving the number of surviving peaks. threshold requires a peak's amplitude to exceed the given level; min_distance (in samples, $\geq 1$ ) enforces a minimum index separation, keeping the taller peak when two lie too close; prominence requires a peak to rise at least that much above the highest saddle connecting it to any taller peak.

Units and uncertainty flow through unchanged: because peaks are a selection of existing samples, each reported extremum retains its original physical unit and its per-sample $σ$ . The threshold and prominence parameters are interpreted in the signal's amplitude unit. This node is stateless — the output depends only on the current input frame, with no memory across calls.

Mathematics

peak at i ⟺ x_{i - 1} < x_{i} > x_{i + 1}

P (i) = x_{i} - max (j \in [l, i] min x_{j}, j \in [i, r] min x_{j})

accept i ⟺ x_{i} > threshold \land P (i) \geq prominence

Examples

Counting spectral lines

Feed the magnitude output of an fft into peak_detection with prominence = 3.0 to reject noise-floor ripple. The peakCount scalar reports how many significant spectral lines are present, while peaks carries their frequencies (as sample positions) and magnitudes for downstream labeling.

Heartbeat detection with spacing

For an ECG sampled at 500 Hz, set min_distance = 200 (0.4 s refractory period) and threshold just above baseline. This suppresses double-counting of the R-wave and its neighbors:

signal_source -> smoothing -> peak_detection(threshold=0.5, min_distance=200, prominence=0.8)

The surviving peaks correspond to individual R-peaks; peakCount divided by the record duration yields heart rate.

Applications

Spectral peak picking after an FFT to identify resonances, harmonics, or emission lines in vibration, acoustic, and optical spectroscopy data.
R-peak / QRS detection and beat counting in biomedical ECG and PPG signals, using min_distance as a physiological refractory constraint.
Event counting and pulse-train analysis in particle physics and photon-counting experiments, where prominence rejects baseline fluctuations.
Chromatography and mass-spectrometry peak enumeration, where threshold and prominence separate analyte peaks from solvent and noise.

Neat

Prominence, borrowed from topography, makes detection scale-robust: a small ripple on a tall shoulder is rejected while an isolated bump of the same height is kept, because acceptance depends on how far a peak descends before reaching higher ground rather than on absolute amplitude alone.

Because valleys are computed as local minima of the same frame, a peak-to-valley pairing gives instantaneous envelope estimates without a separate Hilbert transform.

Known issues

Strict inequality means flat-topped (plateau) maxima where $x_{i-1} = x_i = x_{i+1}$ satisfy neither the peak nor valley condition and are missed; add a tiny dither or smoothing if plateaus are expected.

The first and last samples cannot be classified (no outside neighbor), so extrema landing exactly on a frame boundary are not reported — relevant when processing streamed data in short blocks.