# findpeaks

Locate local maxima (peaks) in a 1-D signal.

## 📝 Syntax

* \[pks, locs, widths, prominences] = findpeaks(Y)
* \[pks, locs, widths, prominences] = findpeaks(Y, Fs, ...)
* \[pks, locs, widths, prominences] = findpeaks(Y, X, ...)

## 📥 Input argument

* Y - vector: input signal (row or column)
* Fs - scalar: sampling frequency (optional). If provided, peak locations are returned in time units.
* X - vector: x-values corresponding to Y (optional). Must have same length as Y.
* Name/Value pairs - name/value options:
* MinPeakHeight: numeric scalar, default -Inf
* MinPeakProminence: numeric scalar >= 0, default 0
* Threshold: numeric scalar >= 0 (min vertical distance from neighbor baseline), default 0
* MinPeakWidth: numeric scalar >= 0, default 0
* MaxPeakWidth: numeric scalar >= 0, default Inf
* MinPeakDistance: numeric scalar >= 0 (in same units as X), default 0
* WidthReference: 'halfprom' (default) or 'halfheight'
* SortStr: 'none' (default), 'ascend' or 'descend'
* NPeaks: positive integer, maximum number of peaks to return (default Inf)
* Annotate: 'peaks' (default) or 'extents' (controls plotting annotation)

## 📤 Output argument

* pks - peak amplitudes
* locs - peak locations (x-values or indices)
* widths - peak widths measured at the specified WidthReference
* prominences - prominence of each peak

## 📄 Description

findpeaks locates local maxima (peaks) in a one-dimensional signal Y.

The algorithm detects candidate peaks, filters them by height and threshold, computes prominence and widths, enforces minimum separation, and returns the requested outputs.

When no outputs are requested, the function plots the signal and marks detected peaks.

## 💡 Examples

Find peaks in a simple signal

```matlab

t = 0:0.01:2*pi;
y = sin(5*t) + 0.2*randn(size(t));
findpeaks(y, t, 'MinPeakProminence', 0.3);

```

Return widths and prominences

```matlab

[pks, locs, widths, proms] = findpeaks(y, 'MinPeakHeight', 0);

```

## 🔗 See also

[max](https://nelson-9.gitbook.io/Nelson/markdown/en/data_analysis/max).

## 🕔 History

| Version | 📄 Description  |
| ------- | --------------- |
| 1.15.0  | initial version |
