Finds the locations of peaks in an observed series (D.B. Baird).
Options
PRINT = string token |
Controls printed output (peaks); default peak |
|---|---|
CURVE = string token |
Shape of curve to fit to peaks (normal, exponential); default norm |
PLOT = string tokens |
What to plot (peaks, trace); default peak |
METHOD = string token |
The method for finding the peaks (additive, local); default addi |
BANDWIDTH = scalar |
Width of window to use when fitting peaks locally, or the number of low points at the edge of each zone when fitting peaks additively; default takes the number of points divided by ten, or six if this is greater |
MINPEAK = scalar |
Minimum height of a peak; no default (must be set) |
MINGAP = scalar |
Minimum number of points between two peaks when METHOD=additive; default 5 |
MINFALL = scalar |
Minimum fall around a peak before a new peak will be found when METHOD=additive; default MINPEAK/10 |
MINCOHERENCY = scalar |
Minimum coherency (i.e. proportion of variation explained) for a peak to be selected when METHOD=local; default 0.1 |
MAXSIGMA = scalar |
The maximum value of sigma for peaks when METHOD=local; default 4*BANDWIDTH |
MAXRESIDUAL = scalar |
Limit on the absolute size of any residual for the adding of peaks to stop when METHOD=additive; default MINPEAK/3 |
WINDOW = scalar |
Window number for the plots; default 3 |
SCREEN = string token |
Whether to clear the screen before plotting or continue plotting on the old screen (clear, keep); default clea |
Parameters
Y = variates |
Series to search for peaks |
|---|---|
X = variates |
X-coordinates for the series; default !(1...n) where n is the number of Y values |
YPEAKS = variates |
Saves the y-values of the peaks |
XPEAKS = variates |
Saves the positions of the peaks |
FITTEDYPEAKS = variates |
Saves the heights of the peaks predicted by the fitted models |
SIGMA = variates |
Saves the sigma values of the fitted Normal or exponential models, which provide a measure of the widths of the peaks |
COHERENCY = variates |
Saves the coherency (i.e. the proportion of variation accounted for) of the model fitted to identify each peak model |
TITLE = texts |
Titles for the plots |
Description
PEAKFINDER looks for peaks in a series of observations supplied, in a variate, by the Y parameter. The X parameter can supply a variate specifying x-values for the series; if this is not set, these are assumed to be the integers 1…n, where n is the number of values in Y.
The peaks are found by fitting curves to the y-values, as specified by setting of the CURVE option:
normal |
fits a Normal curves EXP(-0.5*((X-p)/sigma)**2) |
|---|---|
exponential |
fits exponential curves EXP(-ABS(X-p)/sigma) |
where p is the location of the peak, and sigma is a measure of its width.
The METHOD option controls how the peaks are fitted. With the default setting, additive, PEAKFINDER looks to see whether the series can be divided into separate zones. The criterion is that these must be separated by 2×b y-values of size less than m/2, where the value b is defined by the BANDWIDTH option, and m is defined by the MINPEAK option. MINPEAK must be set, while BANDWIDTH has a default of n/10, or 6 if n is less than 60. Then, in each zone, PEAKFINDER starts by fitting a single curve. If the maximum absolute residual from that fit is greater than the value specified by the MAXRESIDUAL option, it adds another curve. (So the model for Y in that zone is now the sum of two curves.) If the maximum absolute residual from the model is still greater than MAXRESIDUAL, it adds another curve. This continues until either the residuals are all less than MAXRESIDUAL, or the model contains ten curves. The success of the procedure depends on the value of MAXRESIDUAL. The default value is MINPEAK divided by three. Smaller values allow more complicated patterns of peaks to be identified, but may slow the procedure down and cause convergence problems. Two very close peaks can be generated with this method, when the shape of the peak does not follow that specified by the CURVE option. A second additive component at a close location but with a different value of sigma may then be added to provide a better fit to the shape of the peak. The MINGAP and MINFALL options attempt to control this behaviour, and ensure that only a single peak is given. The MINGAP option sets a lower limit on the number of points between any two peaks (default 5), and the MINFALL option sets a lower limit on the fall in y-values between peaks (default MINPEAK/10).
With the alternative setting, METHOD=local, PEAKFINDER fits the specified curve locally around each x-value in turn. The size of the local window for the fit is defined by the BANDWIDTH option, and can be sensitive to the value that is chosen. So this may need to be varied to tune the peak finding process. Ideally it should be equal to the width of the anticipated peaks. The MAXSIGMA option sets an upper limit on the value of sigma for a curve if the corresponding peak is to be accepted (default 4*BANDWIDTH), and the MINCOHERENCY option sets a limit on its coherency i.e. the proportion of variation of Y that the curve accounts for (default 0.1). Increasing MINCOHERENCY requires the peaks to conform more closely to the chosen shape, while increasing MAXSIGMA allows broader and flatter peaks to be found. This method will find only one peak in any area, unless there is valley or flat area of size at least BANDWIDTH between the peaks.
You can set option PRINT=peaks to print the peak locations, the corresponding y-values, their fitted heights, sigma values and coherency. These can also be saved using the XPEAKS, YPEAKS, FITTEDYPEAKS, SIGMA and COHERENCY parameters.
The PLOT option controls the graphs that are displayed, with settings:
peaks |
to plot the fitted peaks, with a horizontal blue line showing the minimum peak height, |
|---|---|
trace |
to plot the components of the fitted model. |
The WINDOW option specifies the window to use for the plots (default 3). The SCREEN option controls whether or not to clear the screen first (default clear). Note, however, that SCREEN is not used with PLOT=trace. You can supply a title for the plots using the TITLE parameter.
Options: PRINT, CURVE, PLOT, METHOD, BANDWIDTH, MINPEAK, MINGAP, MINFALL, MINCOHERENCY, MAXSIGMA, MAXRESIDUAL, WINDOW, SCREEN.
Parameters: Y, X, YPEAKS, XPEAKS, FITTEDYPEAKS, SIGMA, COHERENCY, TITLE.
Action with RESTRICT
Any restrictions on the Y variate are ignored.
See also
Procedures: ALIGNCURVE, BASELINE.
Commands for: Calculations and manipulation.
Example
CAPTION 'PEAKFINDER examples'; STYLE=meta
SET [SEED=8174943]
SCALAR N,NP,S; VALUE=1000,10,30 "Number of points & peaks and sigma"
VARIATE [VALUES=1...N] X
CALCULATE Peak = GRUNIFORM(NP; 0; N) "Random peak positions and amplitude"
& Amp = GRUNIFORM(NP; 0.2; 1)
& P[1...NP] = #Amp*EXP(-0.5*(((X-#Peak)/S)**2))
& YNorm = VSUM(P) + GRUNIFORM(N; 0; 0.2) "Sum Normal peaks"
& P[1...NP] = #Amp*EXP(-ABS(X-#Peak)/S)
& YExp = VSUM(P) + GRUNIFORM(N; 0; 0.2) "Sum Exponential peaks"
PEAKFINDER [PLOT=peaks,trace; METHOD=local; CURVE=normal; BANDWIDTH=60;\
MINPEAK=0.5] YNorm; TITLE='Normal curve, METHOD=local'
PEAKFINDER [PLOT=peaks,trace;METHOD=additive; CURVE=normal;BANDWIDTH=60;\
MINPEAK=0.5] YNorm; TITLE='Normal curve, METHOD=additive'
PEAKFINDER [PLOT=peaks,trace; METHOD=local; CURVE=exponential; BANDWIDTH=60;\
MINPEAK=0.5] YExp; TITLE='Exponential curve, METHOD=local'
PEAKFINDER [PLOT=peaks,trace; METHOD=additive; CURVE=exponential; BANDWIDTH=60;\
MINPEAK=0.5] YExp; XPEAKS=PS; YPEAKS=HT; SIGMA=SH;\
SIGMA=WD; COHERENCY=CH; TITLE='Exponential curve, METHOD=additive'