spectrochempy.find_peaks¶
- find_peaks(dataset, height=None, window_length=3, threshold=None, distance=None, prominence=None, width=None, wlen=None, rel_height=0.5, plateau_size=None, use_coord=True)[source]¶
Wrapper and extension of
scpy.signal.find_peaks
.Find peaks inside a 1D
NDDataset
based on peak properties. This function finds all local maxima by simple comparison of neighbouring values. Optionally, a subset of these peaks can be selected by specifying conditions for a peak’s properties.Warning
This function may return unexpected results for data containing NaNs. To avoid this, NaNs should either be removed or replaced.
- Parameters
dataset (
NDDataset
) – A 1D NDDataset or a 2D NDdataset withlen(X.y) == 1
.height (
float
or array-like, optional, default:None
) – Required height of peaks. Either a number,None
, an array matchingx
or a 2-element sequence of the former. The first element is always interpreted as the minimal and the second, if supplied, as the maximal required height.window_length (
int
, default: 5) – The length of the filter window used to interpolate the maximum. window_length must be a positive odd integer. If set to one, the actual maximum is returned.threshold (
float
or array-like, optional) – Required threshold of peaks, the vertical distance to its neighbouring samples. Either a number,None
, an array matchingx
or a 2-element sequence of the former. The first element is always interpreted as the minimal and the second, if supplied, as the maximal required threshold.distance (
float
, optional) – Required minimal horizontal distance in samples between neighbouring peaks. Smaller peaks are removed first until the condition is fulfilled for all remaining peaks.prominence (
float
or array-like, optional) – Required prominence of peaks. Either a number,None
, an array matchingx
or a 2-element sequence of the former. The first element is always interpreted as the minimal and the second, if supplied, as the maximal required prominence.width (
float
or array-like, optional) – Required width of peaks in samples. Either a number,None
, an array matchingx
or a 2-element sequence of the former. The first element is always interpreted as the minimal and the second, if supplied, as the maximal required width. Floats are interpreted as width measured along the ‘x’ Coord; ints are interpreted as a number of points.wlen (
int
orfloat
, optional) – Used for calculation of the peaks prominences, thus it is only used if one of the argumentsprominence
orwidth
is given. Floats are interpreted as measured along the ‘x’ Coord; ints are interpreted as a number of points. See argument len` inpeak_prominences
of the scipy documentation for a full description of its effects.rel_height (
float
, optional,) – Used for calculation of the peaks width, thus it is only used ifwidth
is given. See argumentrel_height
inpeak_widths
of the scipy documentation for a full description of its effects.plateau_size (
float
or array-like, optional) – Required size of the flat top of peaks in samples. Either a number,None
, an array matchingx
or a 2-element sequence of the former. The first element is always interpreted as the minimal and the second, if supplied as the maximal required plateau size. Floats are interpreted as measured along the ‘x’ Coord; ints are interpreted as a number of points.use_coord (
bool
, optional) – Set whether the x Coord (when it exists) should be used instead of indices for the positions and width. If True, the units of the other parameters are interpreted according to the coordinates.
- Returns
peaks (
ndarray
) – Indices of peaks indataset
that satisfy all given conditions.properties (
dict
) – A dictionary containing properties of the returned peaks which were calculated as intermediate results during evaluation of the specified conditions:peak_heights
If
height
is given, the height of each peak indataset
.
left_thresholds
,right_thresholds
If
threshold
is given, these keys contain a peaks vertical distance to its neighbouring samples.
prominences
,right_bases
,left_bases
If
prominence
is given, these keys are accessible. Seescipy.signal.peak_prominences
for a full description of their content.
width_heights
,left_ips
,right_ips
If
width
is given, these keys are accessible. Seescipy.signal.peak_widths
for a full description of their content.
- plateau_sizes, left_edges’, ‘right_edges’
If
plateau_size
is given, these keys are accessible and contain the indices of a peak’s edges (edges are still part of the plateau) and the calculated plateau sizes.
To calculate and return properties without excluding peaks, provide the open interval
(None, None)
as a value to the appropriate argument (excludingdistance
).
- Warns
PeakPropertyWarning – Raised if a peak’s properties have unexpected values (see
peak_prominences
andpeak_widths
).
See also
find_peaks_cwt
In
scipy.signal
: Find peaks using the wavelet transformation.peak_prominences
In
scipy.signal
: Directly calculate the prominence of peaks.peak_widths
In
scipy.signal
: Directly calculate the width of peaks.
Notes
In the context of this function, a peak or local maximum is defined as any sample whose two direct neighbours have a smaller amplitude. For flat peaks (more than one sample of equal amplitude wide) the index of the middle sample is returned (rounded down in case the number of samples is even). For noisy signals the peak locations can be off because the noise might change the position of local maxima. In those cases consider smoothing the signal before searching for peaks or use other peak finding and fitting methods (like
scipy.signal.find_peaks_cwt
).Some additional comments on specifying conditions:
Almost all conditions (excluding
distance
) can be given as half-open or closed intervals, e.g1
or(1, None)
defines the half-open interval \([1, \infty]\) while(None, 1)
defines the interval \([-\infty, 1]\). The open interval(None, None)
can be specified as well, which returns the matching properties without exclusion of peaks.The border is always included in the interval used to select valid peaks.
For several conditions the interval borders can be specified with arrays matching
dataset
in shape which enables dynamic constrains based on the sample position.The conditions are evaluated in the following order:
plateau_size
,height
,threshold
,distance
,prominence
,width
. In most cases this order is the fastest one because faster operations are applied first to reduce the number of peaks that need to be evaluated later.While indices in
peaks
are guaranteed to be at leastdistance
samples apart, edges of flat peaks may be closer than the alloweddistance
.Use
wlen
to reduce the time it takes to evaluate the conditions forprominence
orwidth
ifdataset
is large or has many local maxima (seescipy.signal.peak_prominences
).
Examples
>>> dataset = scp.read("irdata/nh4y-activation.spg") >>> X = dataset[0, 1800.0:1300.0] >>> peaks, properties = X.find_peaks(height=1.5, distance=50.0, width=0.0) >>> len(peaks.x) 2 >>> peaks.x.values <Quantity([ 1644 1455], 'centimeter^-1')> >>> properties["peak_heights"][0] <Quantity(2.26663446, 'absorbance')> >>> properties["widths"][0] <Quantity(38.729003, 'centimeter^-1')>