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'