peaks: Peaks or local maxima
In aphalo/photobiology: Photobiological Calculations

peaks

R Documentation

Peaks or local maxima

Description

Function that returns a subset of an R object with observations corresponding to local maxima.

Usage

peaks(
  x,
  span,
  global.threshold,
  local.threshold,
  local.reference,
  threshold.range,
  strict,
  na.rm,
  ...
)

## Default S3 method:
peaks(
  x,
  span = NA,
  global.threshold = NA,
  local.threshold = NA,
  local.reference = NA,
  threshold.range = NA,
  strict = NA,
  na.rm = FALSE,
  ...
)

## S3 method for class 'numeric'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  ...
)

## S3 method for class 'data.frame'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  x.var.name = NULL,
  y.var.name = NULL,
  var.name = y.var.name,
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'generic_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = NULL,
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'source_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'response_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'filter_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  filter.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'reflector_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'solute_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'cps_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = "cps",
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'raw_spct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = "counts",
  refine.wl = FALSE,
  method = "spline",
  ...
)

## S3 method for class 'generic_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = NULL,
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'source_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'response_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'filter_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  filter.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'reflector_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'solute_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'cps_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = "cps",
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'raw_mspct'
peaks(
  x,
  span = 5,
  global.threshold = NULL,
  local.threshold = NULL,
  local.reference = "minimum",
  threshold.range = NULL,
  strict = FALSE,
  na.rm = FALSE,
  var.name = "counts",
  refine.wl = FALSE,
  method = "spline",
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

Arguments

`x`	numeric vector. Hint: to find valleys, change the sign of the argument with the unary operator `-`.
`span`	odd positive integer A peak is defined as an element in a sequence which is greater than all other elements within a moving window of width `span` centred at that element. The default value is 5, meaning that a peak is taller than its four nearest neighbours. `span = NULL` extends the span to the whole length of `x`.
`global.threshold`	numeric A value belonging to class `"AsIs"` is interpreted as an absolute minimum height or depth expressed in data units. A bare `numeric` value (normally between 0.0 and 1.0), is interpreted as relative to `threshold.range`. In both cases it sets a global height (depth) threshold below which peaks (valleys) are ignored. A bare negative `numeric` value indicates the global height (depth) threshold below which peaks (valleys) are be ignored. If `global.threshold = NULL`, no threshold is applied and all peaks returned.
`local.threshold`	numeric A value belonging to class `"AsIs"` is interpreted as an absolute minimum height (depth) expressed in data units relative to a within-window computed reference value. A bare `numeric` value (normally between 0.0 and 1.0), is interpreted as expressed in units relative to `threshold.range`. In both cases `local.threshold` sets a local height (depth) threshold below which peaks (valleys) are ignored. If `local.threshold = NULL` or if `span` spans the whole of `x`, no threshold is applied.
`local.reference`	character One of `"minimum"` or `"median"`. The reference used to assess the height of the peak, either the minimum value within the window or the median of all values in the window.
`threshold.range`	numeric vector If of length 2 or a longer vector `range(threshold.range)` is used to scale both thresholds. With `NULL`, the default, `range(x)` is used, and with a vector of length one `range(threshold.range, x)` is used, i.e., the range is expanded.
`strict`	logical flag: if `TRUE`, an element must be strictly greater than all other values in its window to be considered a peak. Default: `FALSE` (since version 0.13.1).
`na.rm`	logical indicating whether `NA` values should be stripped before searching for peaks.
`...`	ignored
`var.name`, `x.var.name`, `y.var.name`	character Name of column where to look for peaks.
`refine.wl`	logical Flag indicating if peak location should be refined by fitting a function.
`method`	character String with the name of a method. Currently only spline interpolation is implemented.
`unit.out`	character One of "energy" or "photon"
`filter.qty`	character One of "transmittance" or "absorbance"
`.parallel`	if TRUE, apply function in parallel, using parallel backend provided by foreach
`.paropts`	a list of additional options passed into the foreach function when parallel computation is enabled. This is important if (for example) your code relies on external data or packages: use the .export and .packages arguments to supply them so that all cluster nodes have the correct environment set up for computing.

Details

Function find_peaks is a wrapper built onto function peaks from splus2R, adds support for peak height thresholds and handles span = NULL and non-finite (including NA) values differently than splus2R::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 selects max(x). Passing 'strict = TRUE' ensures that multiple global and within window maxima are ignored, and can result in no peaks being returned.

Two tests make it possible to ignore irrelevant peaks. One test (global.threshold) is based on the absolute height of the peaks and can be used in all cases to ignore globally low peaks. A second test (local.threshold) is available when the window defined by 'span' does not include all observations and can be used to ignore peaks that are not locally prominent. In this second approach the height of each peak is compared to a summary computed from other values within the window of width equal to span where it was found. In this second case, the reference value used within each window containing a peak is given by local.reference. Parameter threshold.range determines how the values passed as argument to global.threshold and local.threshold are scaled. The default, NULL uses the range of x. Thresholds for ignoring too small peaks are applied after peaks are searched for, and threshold values can in some cases result in no peaks being returned.

While function find_peaks accepts as input a numeric vector and returns a logical vector, methods peaks and valleys accept as input different R objects, including spectra and collections of spectra and return a subset of the object. These methods are implemented using calls to functions find_peaks and fit_peaks.

Value

A subset of x with rows corresponding to local maxima.

Methods (by class)

peaks(default): Default returning always NA.
peaks(numeric): Default function usable on numeric vectors.
peaks(data.frame): Method for "data.frame" objects.
peaks(generic_spct): Method for "generic_spct" objects.
peaks(source_spct): Method for "source_spct" objects.
peaks(response_spct): Method for "response_spct" objects.
peaks(filter_spct): Method for "filter_spct" objects.
peaks(reflector_spct): Method for "reflector_spct" objects.
peaks(solute_spct): Method for "solute_spct" objects.
peaks(cps_spct): Method for "cps_spct" objects.
peaks(raw_spct): Method for "raw_spct" objects.
peaks(generic_mspct): Method for "generic_mspct" objects.
peaks(source_mspct): Method for "source_mspct" objects.
peaks(response_mspct): Method for "cps_mspct" objects.
peaks(filter_mspct): Method for "filter_mspct" objects.
peaks(reflector_mspct): Method for "reflector_mspct" objects.
peaks(solute_mspct): Method for "solute_mspct" objects.
peaks(cps_mspct): Method for "cps_mspct" objects.
peaks(raw_mspct): Method for "raw_mspct" objects.

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 = FALSE.

Examples

# default span = 5
peaks(sun.spct)
# global maximum
peaks(sun.spct, span = NULL)
peaks(sun.spct, span = NULL)$w.length
# fitted peak wavelength
peaks(sun.spct, span = NULL, refine.wl = TRUE)
peaks(sun.spct, span = NULL, refine.wl = TRUE)$w.length
# a wider window
peaks(sun.spct, span = 51)
# global threshold relative to the range of s.e.irrad values
peaks(sun.spct, global.threshold = 0.7)
peaks(sun.spct, global.threshold = -0.3)
# global threshold in actual s.e.irrad values
peaks(sun.spct, global.threshold = 0.7, threshold.range = c(0, 1))
# local threshold  relative to the range of s.e.irrad values
peaks(sun.spct, local.threshold = 0.1)
# local threshold in actual s.e.irrad values
peaks(sun.spct, local.threshold = 0.1, threshold.range = c(0, 1))
# local threshold  relative to the range of s.e.irrad values, using window
# median instead of window minimum
peaks(sun.spct, local.threshold = 0.05, local.reference = "median")
# minimum, the default.
peaks(sun.spct, local.threshold = 0.05, local.reference = "minimum")

peaks(sun.spct)

aphalo/photobiology documentation built on June 10, 2025, 4:09 p.m.