Accelerating the pace of engineering and science

# findpeaks

Find local maxima

## Syntax

• pks = findpeaks(data) example
• [pks,locs] = findpeaks(data) example
• [pks,locs,w,p] = findpeaks(data) example
• [___] = findpeaks(___,Name,Value)

## Description

example

pks = findpeaks(data) returns a vector with the local maxima (peaks) of the input signal vector, data. A local peak is a data sample that is either larger than its two neighboring samples or is equal to Inf. Non-Inf signal endpoints are excluded. If a peak is flat, the function returns only the point with the lowest index.

example

[pks,locs] = findpeaks(data) additionally returns the indices at which the peaks occur.

example

[pks,locs,w,p] = findpeaks(data) additionally returns the widths of the peaks as the vector w and the prominences of the peaks as the vector p.

example

[___] = findpeaks(data,x) specifies x as the location vector and returns any of the output arguments from previous syntaxes. locs and w are expressed in terms of x.

example

[___] = findpeaks(data,Fs) specifies the sample rate, Fs, of the data. The first sample of data is assumed to have been taken at time zero. locs and w are converted to time units.

[___] = findpeaks(___,Name,Value) specifies options using name-value pair arguments in addition to any of the input arguments in previous syntaxes.

example

findpeaks(___) without output arguments plots the signal and overlays the peak values.

## Examples

expand all

### Find Peaks in a Vector

Define a vector with three peaks and plot it.

```data = [25 8 15 5 6 10 10 3 1 20 7];
plot(data)
```

Find the local maxima. The peaks are output in order of occurrence. The first sample is not included despite being the maximum. For the flat peak, the function returns only the point with lowest index.

```pks = findpeaks(data)
```
```pks =

15    10    20

```

Use findpeaks without output arguments to display the peaks.

```findpeaks(data)
```

### Find Peaks and Their Locations

Create a signal that consists of a sum of bell curves. Specify the location, height, and width of each curve.

```x = linspace(0,1,1000);

Pos = [1 2 3 5 7 8]/10;
Hgt = [4 4 4 2 2 3];
Wdt = [2 6 3 3 4 6]/100;

for n = 1:length(Pos)
Gauss(n,:) =  Hgt(n)*exp(-((x - Pos(n))/Wdt(n)).^2);
end

PeakSig = sum(Gauss);
```

Plot the individual curves and their sum.

```plot(x,Gauss,'--',x,PeakSig)
```

Use findpeaks with default settings to find the peaks of the signal and their locations.

```[pks,locs] = findpeaks(PeakSig,x);
```

Plot the peaks using findpeaks and label them.

```findpeaks(PeakSig,x)

text(locs+.02,pks,num2str((1:numel(pks))'))
```

Sort the peaks from tallest to shortest.

```[psor,lsor] = findpeaks(PeakSig,x,'SortStr','descend');

findpeaks(PeakSig,x)

text(lsor+.02,psor,num2str((1:numel(psor))'))
```

### Peak Prominences

Create a signal that consists of a sum of bell curves riding on a full period of a cosine. Specify the location, height, and width of each curve.

```x = linspace(0,1,1000);

base = 4*cos(2*pi*x);

Pos = [1 2 3 5 7 8]/10;
Hgt = [3 7 5 5 4 5];
Wdt = [1 3 3 4 2 3]/100;

for n = 1:length(Pos)
Gauss(n,:) =  Hgt(n)*exp(-((x - Pos(n))/Wdt(n)).^2);
end

PeakSig = sum(Gauss)+base;
```

Plot the individual curves and their sum.

```plot(x,Gauss,'--',x,PeakSig,x,base)
```

Use findpeaks to locate and plot the peaks that have a prominence of at least 4.

```findpeaks(PeakSig,x,'MinPeakProminence',4,'Annotate','extents')
```

The highest and lowest peaks are the only ones that satisfy the condition.

Display the prominences and the widths at half prominence of all the peaks.

```[pks,locs,widths,proms] = findpeaks(PeakSig,x);
widths
proms
```
```widths =

0.0154    0.0431    0.0377    0.0625    0.0274    0.0409

proms =

2.6816    5.5773    3.1448    4.4171    2.9191    3.6363

```

### Find Peaks with Minimum Separation

Sunspots are a cyclic phenomenon. Their number is known to peak roughly every 11 years.

Load the file sunspot.dat, which contains the average number of sunspots observed every year from 1700 to 1987. Find and plot the maxima.

```load sunspot.dat

year = sunspot(:,1);
avSpots = sunspot(:,2);

findpeaks(avSpots,year)
```

Improve your estimate of the cycle duration by ignoring peaks that are very close to each other. Find and plot the peaks again, but now restrict the acceptable peak-to-peak separations to values greater than six years.

```findpeaks(avSpots,year,'MinPeakDistance',6)
```

Use the peak locations returned by findpeaks to compute the mean interval between maxima.

```[pks,locs] = findpeaks(avSpots,year,'MinPeakDistance',6);

meanCycle = mean(diff(locs))
```
```meanCycle =

10.9600

```

### Constrain Peak Features

Load an audio signal sampled at 7418 Hz. Select 200 samples.

```load mtlb
select = mtlb(1001:1200);
```

Find the peaks that have an amplitude of at least 1 V.

```findpeaks(select,Fs,'MinPeakHeight',1)
```

Find the peaks that are at least 1 V higher than their neighboring samples.

```findpeaks(select,Fs,'Threshold',1)
```

Find the peaks that drop at least 1 V on either side before the signal attains a higher value.

```findpeaks(select,Fs,'MinPeakProminence',1)
```

### Determine Peak Widths

Create a signal that consists of a sum of bell curves. Specify the location, height, and width of each curve.

```x = linspace(0,1,1000);

Pos = [1 2 3 5 7 8]/10;
Hgt = [4 4 2 2 2 3];
Wdt = [3 8 4 3 4 6]/100;

for n = 1:length(Pos)
Gauss(n,:) =  Hgt(n)*exp(-((x - Pos(n))/Wdt(n)).^2);
end

PeakSig = sum(Gauss);
```

Plot the individual curves and their sum.

```plot(x,Gauss,'--',x,PeakSig)
```

Measure the widths of the peaks using the half prominence as reference.

```findpeaks(PeakSig,x,'Annotate','extents')
```

Measure the widths again, this time using the half height as reference.

```findpeaks(PeakSig,x,'Annotate','extents','WidthReference','halfheight')
```

## Input Arguments

expand all

### data — Input datavector

Input data, specified as a vector. data must be real and must have at least three elements.

Data Types: single | double

### x — Locationsvector

Locations, specified as a vector. x must increase monotonically and have the same length as data. If x is omitted, then the indices of data are used as locations.

Data Types: single | double

### Fs — Sample ratepositive scalar

Sample rate, specified as a positive scalar. The sample rate is the number of samples per unit time. If the unit of time is seconds, the sample rate has units of hertz.

Data Types: single | double

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'SortStr','descend','NPeaks',3 finds the three tallest peaks of the signal.

### 'NPeaks' — Maximum number of peakspositive integer scalar

Maximum number of peaks to return, specified as the comma-separated pair consisting of 'NPeaks' and a positive integer scalar. findpeaks operates from the first element of the input data and terminates when the number of peaks reaches the value of 'NPeaks'.

Data Types: single | double

### 'SortStr' — Peak sorting'none' (default) | 'ascend' | 'descend'

Peak sorting, specified as the comma-separated pair consisting of 'SortStr' and one of these values:

• 'none' returns the peaks in the order in which they occur in the input data.

• 'ascend' returns the peaks in ascending or increasing order, from the smallest to the largest value.

• 'descend' returns the peaks in descending order, from the largest to the smallest value.

Data Types: char

### 'MinPeakHeight' — Minimum peak height-Inf (default) | real scalar

Minimum peak height, specified as the comma-separated pair consisting of 'MinPeakHeight' and a real scalar. Use this argument to have findpeaks return only those peaks higher than 'MinPeakHeight'. Specifying a minimum peak height can reduce processing time.

Data Types: single | double

### 'MinPeakProminence' — Minimum peak prominence0 (default) | real scalar

Minimum peak prominence, specified as the comma-separated pair consisting of 'MinPeakProminence' and a real scalar. Use this argument to have findpeaks return only those peaks that have a relative importance of at least 'MinPeakProminence'. See Prominence for more information.

Data Types: single | double

### 'Threshold' — Minimum height difference0 (default) | nonnegative real scalar

Minimum height difference between a peak and its neighboring values, specified as the comma-separated pair consisting of 'Threshold' and a nonnegative real scalar. Use this argument to have findpeaks return only those peaks that exceed their neighbors by at least the value of 'Threshold'.

Data Types: single | double

### 'MinPeakDistance' — Minimum peak separation1 (default) | positive integer scalar

Minimum peak distance, or minimum separation between peaks, specified as the comma-separated pair consisting of 'MinPeakDistance' and a positive integer scalar. Use this argument to have findpeaks ignore small peaks that occur in the neighborhood of a larger peak. When you specify a value for 'MinPeakDistance', the algorithm initially identifies all the peaks in the input data and sorts them in descending order. Beginning with the largest peak, the algorithm ignores all identified peaks not separated by more than the value of 'MinPeakDistance'.

Data Types: single | double

### 'WidthReference' — Reference height for width measurements'halfprom' (default) | 'halfheight'

Reference height for width measurements, specified as the comma-separated pair consisting of 'WidthReference' and either 'halfprom' or 'halfheight'. findpeaks estimates the width of a peak as the distance between the points where the descending signal intercepts a horizontal reference line. The points are found by linear interpolation. The height of the line is selected using the criterion specified in 'WidthReference':

• 'halfprom' positions the reference line beneath the peak at a vertical distance equal to half the peak prominence. See Prominence for more information.

• 'halfheight' positions the reference line at one-half the peak height. The line is truncated if any of its intercept points lie beyond the borders of the peaks selected by setting 'MinPeakHeight', 'MinPeakProminence', and 'Threshold'. The border between peaks is defined by the horizontal position of the lowest valley between them. Peaks with height less than zero are discarded.

Data Types: char

### 'MinPeakWidth' — Minimum peak width0 (default) | positive real scalar

Minimum peak width, specified as the comma-separated pair consisting of 'MinPeakWidth' and a positive real scalar. Use this argument to select only those peaks that have widths of at least 'MinPeakWidth'.

Data Types: single | double

### 'MaxPeakWidth' — Maximum peak widthInf (default) | positive real scalar

Maximum peak width, specified as the comma-separated pair consisting of 'MaxPeakWidth' and a positive real scalar. Use this argument to select only those peaks that have widths of at most 'MaxPeakWidth'.

Data Types: single | double

### 'Annotate' — Plot style'peaks' (default) | 'extents'

Plot style, specified as the comma-separated pair consisting of 'Annotate' and one of these values:

• 'peaks' plots the signal and annotates the value of every peak.

• 'extents' plots the signal and annotates the value, width, and prominence of every peak.

This argument is ignored if you call findpeaks with output arguments.

Data Types: char

## Output Arguments

expand all

### pks — Local maximavector

Local maxima, returned as a vector of signal values. If there are no local maxima, then pks is empty.

Data Types: single | double

### locs — Peak indicesvector

Peak indices, returned as a vector of integer indices.

If you specify a location vector, x, then locs contains the values of x at the peak indices. If you specify a sample rate, Fs, then locs is a vector of time instants.

Data Types: single | double

### w — Peak widthsvector

Peak widths, returned as a vector of real numbers. The width of each peak is computed as the distance between the points to the left and right of the peak where the signal intercepts a reference line whose height is specified by WidthReference. The points themselves are found by linear interpolation.

If you specify a location vector, x, then the widths are expressed in terms of x. If you specify a sample rate, Fs, then the widths are expressed in units of time.

Data Types: single | double

### p — Peak prominencesvector

Peak prominences, returned as a vector of real numbers. The prominence of a peak is the minimum vertical distance that the signal must descend on either side of the peak before either climbing back to a level higher than the peak or reaching an endpoint. See Prominence for more information.

Data Types: single | double

expand all

### Prominence

The prominence of a peak measures how much the peak stands out due to its intrinsic height and its location relative to other peaks. A low isolated peak can be more prominent than one that is higher but is an unremarkable member of a tall range.

To measure the prominence of a peak:

1. Place a marker on the peak.

2. Extend a horizontal line from the peak to the left and right until the line does one of the following:

• Crosses the signal because there is a higher peak

• Reaches the left or right end of the signal

3. Find the minimum of the signal in each of the two intervals defined in Step 2. This point is either a valley or one of the signal endpoints.

4. The higher of the two interval minima specifies the reference level. The height of the peak above this level is its prominence.

findpeaks makes no assumption about the behavior of the signal beyond its endpoints, whatever their height. This is reflected in Steps 2 and 4 and often affects the value of the reference level. Consider for example the peaks of this signal:

Peak NumberLeft Interval Lies Between Peak andRight Interval Lies Between Peak andLowest Point on the Left IntervalLowest Point on the Right IntervalReference Level (Highest Minimum)
1Left endCrossing due to peak 2Left endpointaa
2Left endRight endLeft endpointhLeft endpoint
3Crossing due to peak 2Crossing due to peak 4bcc
4Crossing due to peak 2Crossing due to peak 6bdb
5Crossing due to peak 4Crossing due to peak 6dee
6Crossing due to peak 2Right enddhd
7Crossing due to peak 6Crossing due to peak 8fgg
8Crossing due to peak 6Right endfhf
9Crossing due to peak 8Crossing due to right endpointhii