SignalProcessing
FindPeakPoints
find peak and valley points of one-dimensional data sets
Calling Sequence
Parameters
Options
Description
Examples
Compatibility
FindPeakPoints( X, Y, options )
FindPeakPoints( XY, options )
FindPeakPoints( Y, options )
X
-
one-dimensional rtable or list of independent data values
Y
one-dimensional rtable or list of dependent data values
XY
two-dimensional rtable or list of independent and dependent data values, with each row representing a single point
sortdata - Either true or false, this specifies whether to sort the data when both independent and dependent values are provided. The default is true.
tolerance - Threshold used to detect a peak or a valley. See the precise definition of "peaks" and "valleys" in terms of tolerance below. Typically, a peak must be higher by more than tolerance than the closest valleys on the left and right. The default is 0.0.
breadthtype - The definition used to determine the breadth of a peak or valley. There are three options:
baseradius: The smaller of the positive horizontal distances from the peak (valley) to the valleys (peaks) on either side which determine the prominence. This is the default.
basewidth: The horizontal distance between the valleys (peaks) on either side of the peak (valley) which determine the prominence.
halfprominence: The horizontal distance between the intersection points of the (imaginary) lines from the peak (valley) to the valleys (peaks) which determine the prominence, and the (imaginary) horizontal line that is halfway between the peak (valley) and the valley (peak) which determines the prominence.
includeendpoints - Specifies if the endpoints of the data should be kept or filtered out if they're found to be peaks or valleys. The default is true.
minimumprominence - Specifies the smallest allowed prominence to filter the peaks/valleys. The default is 0.0.
minimumbreadth - Specifies the smallest allowed breadth to filter the peaks/valleys. The default is 0.0.
minimumheight - Specifies the smallest allowed height to filter the peaks and valleys. The default is -infinity.
maximumheight - Specifies the largest allowed height to filter the peaks and valleys. The default is infinity.
minimumseparation - Specifies the smallest horizontal distance of a candidate extremum from the previous extremum of the same variety (peak or valley) to be included. for a successive point (of the same variety) to count. The default is 0.0.
output - The type of output. The supported options are:
peaks: For a Matrix of the peak points. This is the default.
valleys: Similar to peaks, but for valleys.
extremes: For a Matrix of both the peak and valley points.
peakindices: For a column Vector of the indices of the peak points.
valleyindices: For a column Vector of the indices of the valley points.
extremeindices: For a column Vector of the indices of the extreme points.
peakbreadths: For a column Vector of the breadths of the peak points.
valleybreadths: For a column Vector of the breadths of the valley points.
peakprominences: For a column Vector of the prominences of the peak points.
valleyprominences: For a column Vector of the prominences of the valley points.
plot: Returns a plot of all the points, using the plot options below or any options which can be passed to plots:-display.
record: Returns a record with the previous options.
list of any of the above options: Returns an expression sequence with the corresponding outputs, in the same order.
plotincludepoints - A list of point types (chosen from peaks, regular, and valleys) to include in the plot. The default is [peaks].
curveplotoptions - A list of options to be passed to the internal call to plot when generating the curve through all the points. The default is [connect=true,thickness=1,color=black]. Note: Any passed options will not overwrite the remaining default ones.
peakpointplotoptions - A list of options to be passed to plots:-pointplot when generating the point plot for peaks. The default is [color=blue,symbol=solidcircle,symbolsize=15]. Note: Any passed options will not overwrite the remaining default ones.
valleypointplotoptions - A list of options to be passed to plots:-pointplot when generating the point plot for valleys. The default is [color=green,symbol=solidcircle,symbolsize=15]. Note: Any passed options will not overwrite the remaining default ones.
regularpointplotoptions - A list of options to be passed to plots:-pointplot when generating the point plot for regular points. The default is [color=black,symbol=solidcircle,symbolsize=10]. Note: Any passed options will not overwrite the remaining default ones.
The FindPeakPoints command is used to find the "peak" and "valley" points of one-dimensional data sets.
The command can be accessed by using either the long form or the short form of the command name in the calling sequence.
The long form, SignalProcessing:-FindPeakPoints, is always available. The short form can be used after loading the package.
For the FindPeakPoints(X,Y) calling sequence, X and Y must be of the same size.
The FindPeakPoints(XY) calling sequence is reduced to the FindPeakPoints(X,Y) calling sequence by taking X and Y to be, respectively, the first and second columns of XY. Similarly, the FindPeakPoints(Y) calling sequence is reduced to the FindPeakPoints(X,Y) calling sequence by taking X to be a Vector of the positive integers from 1 to numelems(Y).
Any input rtable/list is converted to an rtable of float[8] datatype, and an error is thrown if this is not possible. For this reason, it is most efficient for any input to already be an rtable having the appropriate datatype. Note: The rtables cannot have an indexing function, and they need to have rectangular storage.
When both independent and dependent data are passed, if sortdata=true then the independent values are sorted in increasing order, and the dependent values are sorted in tandem. If sortdata=false, on the other hand, the onus is on the user to ensure that the data is sorted.
Prior to filtering based on breadth, height, prominence, and separation, the command determines a "peak" ("valley") to be a point which satisfies the following recursive conditions:
The closest "extremum" on the left of the point, if it exists, is a "valley" ("peak") which is lower (higher) by more than tolerance.
When moving to the right of the point, before a point that is of greater (lower) height is encountered, one reaches either an endpoint in the situation where a point to the left has already been determined to be a "valley" ("peak"), or a point lower (higher) in height by more than tolerance.
Note: Points passed over between the starting and final points during this sweep to the right are "regular".
Note: Peaks and valleys are found by considering the entire neighborhood of the candidate points, not just the closest points on the left and right.
The "left-prominence" of a peak is defined as the height difference between the peak and the lowest valley between it and the closest peak (or endpoint) on the left of equal or greater height. Note: In the event of a tie, the lowest valley furthest from the peak is taken. The "right-prominence" is similarly defined, and the overall "prominence" is taken to be the smaller of the positive one-sided prominences. The prominence of a valley is defined in the same manner. Note: The missing one-sided prominences for the endpoints are taken to be zero.
Starting with Maple 2024, FindPeakPoints uses external code for the intensive computations, and runs considerably faster than in previous versions.
withSignalProcessing:
Simple Examples
For a simple example, consider:
X≔1,5,8,10
Y≔5,10,1,4
P,V≔FindPeakPointsX,Y,includeendpoints=false,output=peaks,valleys
P,V≔?,?
FindPeakPointsX,Y,includeendpoints=false,output=plot,plotincludepoints=peaks,regular,valleys
Saw:
FindPeakPoints1,2,1,2,1,2,1,output=plot,plotincludepoints=peaks,regular,valleys
Plateau:
FindPeakPoints1,2,2,2,1,output=plot,plotincludepoints=peaks,regular,valleys
Step:
FindPeakPoints1,2,2,2,3,output=plot,plotincludepoints=peaks,regular,valleys
Hat:
FindPeakPoints1,1,2,1,1,output=plot,plotincludepoints=peaks,regular,valleys
Plain:
FindPeakPoints2,2,2,2,output=plot,plotincludepoints=peaks,regular,valleys
Illustrative Example
Consider now a more illustrative example:
data≔Vectorrow5,10,8,9,8,10,10,10,7,7.1,7.2,7.3,7.4,7.5,2,12,12,12,15.1,14.9,15.2,10,20.1,20.2,20.1,25,15
data≔
Options:
opts≔output=record,plotincludepoints=peaks,regular,valleys,curveplotoptions=connect=true,color=red,thickness=2,peakpointplotoptions=symbolsize=20,color=blue,valleypointplotoptions=symbolsize=20,color=green,regularpointplotoptions=symbolsize=15,color=black,title=Peaks and Valleys:
L≔FindPeakPointsdata,opts
The peaks and valleys:
P,V≔Lpeaks,Lvalleys
The plot:
Lplot
If we increase the tolerance, some extrema are excluded:
L≔FindPeakPointsdata,tolerance=0.2,opts:
The remaining peaks and valleys:
Minimum and Maximum Height
Peaks and valleys can be filtered based on the height:
data≔−5,12,6,7,3,15,−10
FindPeakPointsdata,output=plot,plotincludepoints=peaks,regular,valleys,gridlines=true
FindPeakPointsdata,minimumheight=0,maximumheight=10,output=plot,plotincludepoints=peaks,regular,valleys,gridlines=true
PeakIndices,ValleyIndices≔FindPeakPointsdata,minimumheight=0,maximumheight=10,output=peakindices,valleyindices
PeakIndices,ValleyIndices≔?,?
Prominence
The command can be used to isolate the most prominent peak. Consider:
data≔Vectorrow8,10,5,7,1,6,5,15,4,6,5,7,3,10,8
L≔FindPeakPointsdata,output=record,plotincludepoints=peaks,regular,valleys,gridlines=true
Isolating the peaks, along with the breadths and prominences:
P,PB,PP≔Lpeaks,Lpeakbreadths,Lpeakprominences
P,PB,PP≔?,?,?
Isolating the valleys, along with the breadths and prominences:
V,VB,VP≔Lvalleys,Lvalleybreadths,Lvalleyprominences
V,VB,VP≔?,?,?
Isolating the plot:
One peak stands out with a prominence of 12, and can be singled out:
FindPeakPointsdata,minimumprominence=10,output=plot
Breadth
The breadth of a peak/valley can be measured in multiple ways:
A≔6,10,6,2,6,10,6
FindPeakPointsA,output=plot,plotincludepoints=peaks,regular,valleys
PB1,VB1≔FindPeakPointsA,output=peakbreadths,valleybreadths,breadthtype=baseradius
PB1,VB1≔?,?
PB2,VB2≔FindPeakPointsA,output=peakbreadths,valleybreadths,breadthtype=basewidth
PB2,VB2≔?,?
PB3,VB3≔FindPeakPointsA,output=peakbreadths,valleybreadths,breadthtype=halfprominence
PB3,VB3≔?,?
An appropriate measure of breadth can also be used to retain specific peaks. For instance:
B≔Vectorcolumn5,10,4,8,4,9,3,7,3,8,2,6,2,7,1
FindPeakPointsB,breadthtype=basewidth,minimumbreadth=3,output=plot
Minimum Separation
The FindPeakPoints command can filter out peaks and valleys that are too close:
data≔Matrixseqi,2+−1i,i=1..11
FindPeakPointsdata,output=plot,plotincludepoints=peaks,regular,valleys
FindPeakPointsdata,minimumseparation=4.0,output=plot,plotincludepoints=peaks,regular,valleys
FindPeakPointsdata,minimumseparation=5.0,output=plot,plotincludepoints=peaks,regular,valleys
Extremes
All extremes (peaks and valleys) can be returned together:
T,X≔GenerateSignalsin2t+12cos5t,t=0..2π,103,output=times,signal:
FindPeakPointsT,X,output=plot
E≔FindPeakPointsT,X,output=extremes
plots:-pointplotE,connect,color=blue,title=Plot of Extremes,font=Verdana,15
Sunspot Periodicity
For a real-world, so-to-speak, example, we can look to the sun (well, don't, that's dangerous), and find the period of the number of sunspots. First, obtain the data:
datafile≔FileTools:-JoinPathkerneloptsdatadir,datasets,sunspots.csv
datafile≔/maple/cbat/active/277890/data/datasets/sunspots.csv
data≔ImportMatrixdatafile,delimiter=,2..
Now, plot the data:
P≔plots:-pointplotdata,labels=Year,Wolf Number,labeldirections=horizontal,vertical,connect=true,title=Sunspot Data,font=Verdana,15,labelfont=Verdana,15,thickness=0,gridlines,size=800,golden
Find the peaks:
B≔FindPeakPointsdata,output=record,plotincludepoints=peaks,peakpointplotoptions=symbolsize=10,minimumprominence=25,labels=Year,Wolf Number,labeldirections=horizontal,vertical,size=1000,500,view=1650..2050,0..300,xtickmarks=seq1700..2050,50:
We choose a minimum prominence here to be 25 in order to filter out the spurious peaks. The option, say, tolerance=15 would achieve this as well.
Display the plot:
Bplot
Finally, determine the period:
Q≔Bpeaks..,1
α≔MeanQ2..−Q..−2
α≔11.
The SignalProcessing[FindPeakPoints] command was introduced in Maple 2019.
For more information on Maple 2019 changes, see Updates in Maple 2019.
The 'sortdata' and 'maximumheight' options were introduced in Maple 2021.
For more information on Maple 2021 changes, see Updates in Maple 2021.
The SignalProcessing[FindPeakPoints] command was updated in Maple 2024.
The 'output' option was updated in Maple 2024.
See Also
plot
plots:-display
plots:-pointplot
Download Help Document
