Find local maxima or global maximum (peaks)

This method finds peaks (local maxima) in a vector, using a user selectable span and size threshold relative to the tallest peak (global maximum).

Usage

find_peaks(x, ignore_threshold = 0, span = 3, strict = FALSE, na.rm = FALSE)

Arguments

x: numeric vector.
ignore_threshold: numeric value between 0.0 and 1.0 indicating the size threshold below which peaks will be ignored, or a negative value >= -1, to ignore peaks above a threshold. These values are relative to the range of x.
span: a peak is defined as an element in a sequence which is greater than all other elements within a window of width span centered at that element. The default value is 3, meaning that a peak is bigger than both of its neighbors. span = NULL extends the span to the whole length of x.
strict: logical flag: if TRUE, an element must be strictly greater than all other values in its window to be considered a peak. Default: TRUE.
na.rm: logical indicating whether NA values should be stripped before searching for peaks.

Value

A vector of logical values. Values that are TRUE correspond to local peaks in vector x and can be used to extract the rows corresponding to peaks from a data frame.

Details

This function is a wrapper built onto function peaks from splus2R and handles non-finite (including NA) values differently than peaks, instead of giving an error when na.rm = FALSE and x contains NA values, NA values are replaced with the smallest finite value in x. span = NULL is treated as a special case and returns max(x).

Note

The default for parameter strict is FALSE in functions peaks() and find_peaks(), as in stat_peaks() and in stat_valleys(), while the default in peaks is strict = TRUE.

Examples

# lynx is a time.series object
lynx_num.df <-
  try_tibble(lynx,
             col.names = c("year", "lynx"),
             as.numeric = TRUE) # years -> as numeric

which(find_peaks(lynx_num.df$lynx, span = 31))
#> [1] 46 65 84
lynx_num.df[find_peaks(lynx_num.df$lynx, span = 15), ]
#> # A tibble: 11 × 2
#>     year  lynx
#>    <dbl> <dbl>
#>  1  1828  5943
#>  2  1838  3409
#>  3  1848  2536
#>  4  1857  2871
#>  5  1866  6721
#>  6  1875  2251
#>  7  1885  4431
#>  8  1895  4031
#>  9  1904  6991
#> 10  1913  3800
#> 11  1925  3574
lynx_num.df[find_peaks(lynx_num.df$lynx, span = NULL), ]
#> # A tibble: 1 × 2
#>    year  lynx
#>   <dbl> <dbl>
#> 1  1904  6991
lynx_num.df[find_peaks(lynx_num.df$lynx,
                       span = 31,
                       ignore_threshold = 0.75), ]
#> # A tibble: 2 × 2
#>    year  lynx
#>   <dbl> <dbl>
#> 1  1866  6721
#> 2  1904  6991

lynx_datetime.df <-
   try_tibble(lynx,
              col.names = c("year", "lynx")) # years -> POSIXct

which(find_peaks(lynx_datetime.df$lynx, span = 31))
#> [1] 46 65 84
lynx_datetime.df[find_peaks(lynx_datetime.df$lynx, span = 31), ]
#> # A tibble: 3 × 2
#>   year        lynx
#>   <date>     <dbl>
#> 1 1866-01-01  6721
#> 2 1885-01-01  4431
#> 3 1904-01-01  6991
lynx_datetime.df[find_peaks(lynx_datetime.df$lynx,
                            span = 31,
                            ignore_threshold = 0.75), ]
#> # A tibble: 2 × 2
#>   year        lynx
#>   <date>     <dbl>
#> 1 1866-01-01  6721
#> 2 1904-01-01  6991