peaks: peaks

In nicholascarey/caRey: Collection of Useful R Functions

peaks

Description

Identify peaks and troughs in oscillating data.

Usage

peaks(x, span = NULL, prominence = NULL, partial = TRUE, smooth.method
  = NULL, smooth.n = NULL, plot = TRUE, plot.which = "b")

Arguments

x	numeric. A numeric vector.
span	numeric. Sets window size for peak (or trough) identification; to be designated a peak, a value must be the highest value (lowest for troughs) within a rolling window of width span. Can be entered as either a window of number of values, or value between 0 and 1 of proportion of total data length. See Details.
prominence	numeric. Value between 0 and 1. Sets threshold for peak or trough 'prominence'. See Details.
partial	logical. Default TRUE. Should the function attempt to identify peaks or troughs at the start or end of the vector where the span window is truncated? See Details.
smooth.method	string. Method by which to smooth data before peak identification. Optional. Default is NULL. See smoother().
smooth.n	numeric. Smoothing factor. See smoother().
plot	logical. Plots the result.
plot.which	string. What to plot: "p" for peaks, "t" for troughs, or the default "b" for both.

Details

peaks scans a vector of numeric values and identifies peaks and troughs.

The required input (span) and two optional inputs (smoothing and height), need to be balanced to successfully identify peaks and troughs. Characteristics such as data noisiness, amplitude, wavelength etc will affect how important each of these are and how successful the identification process is.

span

The most important parameter in determining peaks is the span, which sets the threshold for identification. A rolling window of width span moves across the data, and to be designated a peak a value (after any smoothing) must be the highest value within that window (or lowest value for troughs). The span window can be entered as an integer number of values (e.g. span = 11), or if between 0 and 1 is a proportion of the total data length (e.g. span = 0.1). Note: strictly speaking, the function tests floor(span/2) values before and after each central value, therefore any even span inputs are rounded up. That is span = 10 and span = 11 will both result in an effective moving window of 11 values, with the central value tested against the 5 values before and after it.

Smoothing

For noisy data there is optional smoothing functionality via the smooth_method input. See smoother() for the methods available and appropriate smooth.n values. smooth.method = "spline" works particularly well for oscillating data.

Prominence

Peak identification is also affected by the optional prominence argument. This sets a threshold of 'prominence' for peak identification (equivalent to 'depth' for a trough). This should be a value between 0 and 1 describing a proportion of the total range of the data. Only peaks or troughs containing a range equal to or above this proportion within their span window will be retained. Essentially the higher this is set, the more prominent the peaks must be to be identified (or deeper the troughs). To help with choosing appropriate values, ranges for peaks and troughs are included in the output. Peaks and troughs can have different prominence thresholds: simply enter them as a vector of two values in peak-trough order. E.g. prominence = c(0.2, 0.1).

Equal values within a span window

If there happens to be equal values within a span window, the first occurrence is designated as the peak or trough. If peaks or troughs are being missed because of this, use a lower span. If there are many instances of equal values, try smoothing the data.

Partial windows

A rolling window of width span is used across the data to identify peaks. At the start and end of the data vector this window will overlap the start and end. The default partial = TRUE input tells the function to attempt to identify peaks near the start/end of the data where the span width window is not complete. Change this to FALSE if you see odd matching behaviour at the start or end of the data.

Plot

If plot = TRUE a plot is produced of the data with peaks and/or troughs highlighted. If the data has been smoothed this will be a 2-panel plot of both data sets, otherwise it is the raw data. plot.which controls what results are plotted. The default plot.which = "b" means both peaks (green points and lines) and troughs (blue points and lines) are highlighted within the data. Change to plot.which = "p" to plot only peaks, or plot.which = "t" for only troughs. This does not affect the output object.

Output

The output of the function is a list object of class peaks containing the following elements which can be extracted via the $ operator for further use:

• data - original data input

• data_smooth - smoothed data. Identical to data if no smoothing applied

• peaks - index of locations of identified peaks

• troughs - index of locations of identified troughs

• both - index of locations of both peaks and troughs

• peaks_range - proportional data range within the span window of each peak

• troughs_range - proportional data range within the span window of each trough

• both_range - proportional data range within the span window of each peak and trough

• call - the function call

Author(s)

Nicholas Carey - [e-mail]

Examples

peaks(swim_y.rd, span = 5, smooth.method = "spline", smooth.n = 0.4, plot.which = "p")

nicholascarey/caRey documentation built on Sept. 30, 2023, 3:47 a.m.