# `signal._peak_finding`¶

Functions for identifying peaks in signals.

## Module Contents¶

### Functions¶

 `_boolrelextrema`(data,comparator,axis=0,order=1,mode=”clip”) Calculate the relative extrema of data. `argrelmin`(data,axis=0,order=1,mode=”clip”) Calculate the relative minima of data. `argrelmax`(data,axis=0,order=1,mode=”clip”) Calculate the relative maxima of data. `argrelextrema`(data,comparator,axis=0,order=1,mode=”clip”) Calculate the relative extrema of data. `_identify_ridge_lines`(matr,max_distances,gap_thresh) Identify ridges in the 2-D matrix. `_filter_ridge_lines`(cwt,ridge_lines,window_size=None,min_length=None,min_snr=1,noise_perc=10) Filter ridge lines according to prescribed criteria. Intended `find_peaks_cwt`(vector,widths,wavelet=None,max_distances=None,gap_thresh=None,min_length=None,min_snr=1,noise_perc=10) Attempt to find the peaks in a 1-D array.
`_boolrelextrema`(data, comparator, axis=0, order=1, mode="clip")

Calculate the relative extrema of data.

Relative extrema are calculated by finding locations where `comparator(data[n], data[n+1:n+order+1])` is True.

data : ndarray
Array in which to find the relative extrema.
comparator : callable
Function to use to compare two data points. Should take two arrays as arguments.
axis : int, optional
Axis over which to select from data. Default is 0.
order : int, optional
How many points on each side to use for the comparison to consider `comparator(n,n+x)` to be True.
mode : str, optional
How the edges of the vector are treated. ‘wrap’ (wrap around) or ‘clip’ (treat overflow as the same as the last (or first) element). Default ‘clip’. See numpy.take
extrema : ndarray
Boolean array of the same shape as data that is True at an extrema, False otherwise.

argrelmax, argrelmin

```>>> testdata = np.array([1,2,3,2,1])
>>> _boolrelextrema(testdata, np.greater, axis=0)
array([False, False,  True, False, False], dtype=bool)
```
`argrelmin`(data, axis=0, order=1, mode="clip")

Calculate the relative minima of data.

data : ndarray
Array in which to find the relative minima.
axis : int, optional
Axis over which to select from data. Default is 0.
order : int, optional
How many points on each side to use for the comparison to consider `comparator(n, n+x)` to be True.
mode : str, optional
How the edges of the vector are treated. Available options are ‘wrap’ (wrap around) or ‘clip’ (treat overflow as the same as the last (or first) element). Default ‘clip’. See numpy.take
extrema : tuple of ndarrays
Indices of the minima in arrays of integers. `extrema[k]` is the array of indices of axis k of data. Note that the return value is a tuple even when data is one-dimensional.

argrelextrema, argrelmax

This function uses argrelextrema with np.less as comparator.

New in version 0.11.0.

```>>> from scipy.signal import argrelmin
>>> x = np.array([2, 1, 2, 3, 2, 0, 1, 0])
>>> argrelmin(x)
(array([1, 5]),)
>>> y = np.array([[1, 2, 1, 2],
...               [2, 2, 0, 0],
...               [5, 3, 4, 4]])
...
>>> argrelmin(y, axis=1)
(array([0, 2]), array([2, 1]))
```
`argrelmax`(data, axis=0, order=1, mode="clip")

Calculate the relative maxima of data.

data : ndarray
Array in which to find the relative maxima.
axis : int, optional
Axis over which to select from data. Default is 0.
order : int, optional
How many points on each side to use for the comparison to consider `comparator(n, n+x)` to be True.
mode : str, optional
How the edges of the vector are treated. Available options are ‘wrap’ (wrap around) or ‘clip’ (treat overflow as the same as the last (or first) element). Default ‘clip’. See numpy.take.
extrema : tuple of ndarrays
Indices of the maxima in arrays of integers. `extrema[k]` is the array of indices of axis k of data. Note that the return value is a tuple even when data is one-dimensional.

argrelextrema, argrelmin

This function uses argrelextrema with np.greater as comparator.

New in version 0.11.0.

```>>> from scipy.signal import argrelmax
>>> x = np.array([2, 1, 2, 3, 2, 0, 1, 0])
>>> argrelmax(x)
(array([3, 6]),)
>>> y = np.array([[1, 2, 1, 2],
...               [2, 2, 0, 0],
...               [5, 3, 4, 4]])
...
>>> argrelmax(y, axis=1)
(array([0]), array([1]))
```
`argrelextrema`(data, comparator, axis=0, order=1, mode="clip")

Calculate the relative extrema of data.

data : ndarray
Array in which to find the relative extrema.
comparator : callable
Function to use to compare two data points. Should take two arrays as arguments.
axis : int, optional
Axis over which to select from data. Default is 0.
order : int, optional
How many points on each side to use for the comparison to consider `comparator(n, n+x)` to be True.
mode : str, optional
How the edges of the vector are treated. ‘wrap’ (wrap around) or ‘clip’ (treat overflow as the same as the last (or first) element). Default is ‘clip’. See numpy.take.
extrema : tuple of ndarrays
Indices of the maxima in arrays of integers. `extrema[k]` is the array of indices of axis k of data. Note that the return value is a tuple even when data is one-dimensional.

argrelmin, argrelmax

New in version 0.11.0.

```>>> from scipy.signal import argrelextrema
>>> x = np.array([2, 1, 2, 3, 2, 0, 1, 0])
>>> argrelextrema(x, np.greater)
(array([3, 6]),)
>>> y = np.array([[1, 2, 1, 2],
...               [2, 2, 0, 0],
...               [5, 3, 4, 4]])
...
>>> argrelextrema(y, np.less, axis=1)
(array([0, 2]), array([2, 1]))
```
`_identify_ridge_lines`(matr, max_distances, gap_thresh)

Identify ridges in the 2-D matrix.

Expect that the width of the wavelet feature increases with increasing row number.

matr : 2-D ndarray
Matrix in which to identify ridge lines.
max_distances : 1-D sequence
At each row, a ridge line is only connected if the relative max at row[n] is within `max_distances`[n] from the relative max at row[n+1].
gap_thresh : int
If a relative maximum is not found within max_distances, there will be a gap. A ridge line is discontinued if there are more than gap_thresh points without connecting a new relative maximum.
ridge_lines : tuple
Tuple of 2 1-D sequences. `ridge_lines`[ii][0] are the rows of the ii-th ridge-line, `ridge_lines`[ii][1] are the columns. Empty if none found. Each ridge-line will be sorted by row (increasing), but the order of the ridge lines is not specified.

Bioinformatics (2006) 22 (17): 2059-2065. :doi:`10.1093/bioinformatics/btl355` http://bioinformatics.oxfordjournals.org/content/22/17/2059.long

```>>> data = np.random.rand(5,5)
>>> ridge_lines = _identify_ridge_lines(data, 1, 1)
```

This function is intended to be used in conjunction with cwt as part of find_peaks_cwt.

`_filter_ridge_lines`(cwt, ridge_lines, window_size=None, min_length=None, min_snr=1, noise_perc=10)

Filter ridge lines according to prescribed criteria. Intended to be used for finding relative maxima.

cwt : 2-D ndarray
Continuous wavelet transform from which the ridge_lines were defined.
ridge_lines : 1-D sequence
Each element should contain 2 sequences, the rows and columns of the ridge line (respectively).
window_size : int, optional
Size of window to use to calculate noise floor. Default is `cwt.shape[1] / 20`.
min_length : int, optional
Minimum length a ridge line needs to be acceptable. Default is `cwt.shape[0] / 4`, ie 1/4-th the number of widths.
min_snr : float, optional
Minimum SNR ratio. Default 1. The signal is the value of the cwt matrix at the shortest length scale (`cwt[0, loc]`), the noise is the noise_perc`th percentile of datapoints contained within a window of `window_size around `cwt[0, loc]`.
noise_perc : float, optional
When calculating the noise floor, percentile of data points examined below which to consider noise. Calculated using scipy.stats.scoreatpercentile.

Bioinformatics (2006) 22 (17): 2059-2065. :doi:`10.1093/bioinformatics/btl355` http://bioinformatics.oxfordjournals.org/content/22/17/2059.long

`find_peaks_cwt`(vector, widths, wavelet=None, max_distances=None, gap_thresh=None, min_length=None, min_snr=1, noise_perc=10)

Attempt to find the peaks in a 1-D array.

The general approach is to smooth vector by convolving it with wavelet(width) for each width in widths. Relative maxima which appear at enough length scales, and with sufficiently high SNR, are accepted.

vector : ndarray
1-D array in which to find the peaks.
widths : sequence
1-D array of widths to use for calculating the CWT matrix. In general, this range should cover the expected width of peaks of interest.
wavelet : callable, optional
Should take two parameters and return a 1-D array to convolve with vector. The first parameter determines the number of points of the returned wavelet array, the second parameter is the scale (width) of the wavelet. Should be normalized and symmetric. Default is the ricker wavelet.
max_distances : ndarray, optional
At each row, a ridge line is only connected if the relative max at row[n] is within `max_distances[n]` from the relative max at `row[n+1]`. Default value is `widths/4`.
gap_thresh : float, optional
If a relative maximum is not found within max_distances, there will be a gap. A ridge line is discontinued if there are more than gap_thresh points without connecting a new relative maximum. Default is the first value of the widths array i.e. widths[0].
min_length : int, optional
Minimum length a ridge line needs to be acceptable. Default is `cwt.shape[0] / 4`, ie 1/4-th the number of widths.
min_snr : float, optional
Minimum SNR ratio. Default 1. The signal is the value of the cwt matrix at the shortest length scale (`cwt[0, loc]`), the noise is the noise_perc`th percentile of datapoints contained within a window of `window_size around `cwt[0, loc]`.
noise_perc : float, optional
When calculating the noise floor, percentile of data points examined below which to consider noise. Calculated using stats.scoreatpercentile. Default is 10.
peaks_indices : ndarray
Indices of the locations in the vector where peaks were found. The list is sorted.

cwt

This approach was designed for finding sharp peaks among noisy data, however with proper parameter selection it should function well for different peak shapes.

The algorithm is as follows:
1. Perform a continuous wavelet transform on vector, for the supplied widths. This is a convolution of vector with wavelet(width) for each width in widths. See cwt
2. Identify “ridge lines” in the cwt matrix. These are relative maxima at each row, connected across adjacent rows. See identify_ridge_lines
3. Filter the ridge_lines using filter_ridge_lines.

New in version 0.11.0.

 [1] Bioinformatics (2006) 22 (17): 2059-2065. :doi:`10.1093/bioinformatics/btl355` http://bioinformatics.oxfordjournals.org/content/22/17/2059.long
```>>> from scipy import signal
>>> xs = np.arange(0, np.pi, 0.05)
>>> data = np.sin(xs)
>>> peakind = signal.find_peaks_cwt(data, np.arange(1,10))
>>> peakind, xs[peakind], data[peakind]
([32], array([ 1.6]), array([ 0.9995736]))
```