eegR: Analyze EEG Signals

Description Usage Arguments Details Value Note Examples

findExtrema identifies local (or global) peaks and valleys of a vector (or subviews of a matrix or array).

findExtrema(
  x,
  n = 1L,
  global = FALSE,
  along_dim = 1L,
  tail = c("if_plateau", "never", "do_not_care"),
  constant = 3L,
  topN = NULL,
  has_NA = NULL
)

`x`	an integer or numeric vector, matrix, or array
`n`	the number of neighbouring points (default: 1L) to the left and to the right of each data point; a data point is a local minimum/maximum if it is below/above all data points in its neighbourhood. See also Details.
`global`	logical value whether global extrema should be identified instead of local extrema (default: FALSE). If TRUE, `n` is ignored. See Note.
`along_dim`	the dimension of `x` which defines the vectors that should be tested for local extrema. If `along_dim` is of type character, `x` must have named dimnames.
`tail`	character string defining how tails should be handled (might be abbreviated): "if_plateau" (the default) means extrema at the tails of the vector are only valid if they are part of a plateau; "never" means no extrema at the tails; "do_not_care" means no special treatment of extrema at the tails
`constant`	the value (an integer value between 0 and 3 or NA) which should be assigned to the elements of constant vectors (default: 3L)
`topN`	a positive integer scalar; if not NULL (the default), the local extrema must be among the top N highest/lowest extrema to be marked as such. If there are ties, all of them are returned.
`has_NA`	if FALSE, x is not checked for missing values, thereby speeding up the computations; if has_NA is NULL (default), a fast check is performed and if x has missing values, special corrections are applied (see Details).

There are four special features of findExtrema. First, repeated neighbouring values ('plateaus') are treated as if they were a single data point. This has two consequences: 1) If the plateau is a local extrema, all points of the plateau are considered as extrema. 2) The argument 'n' of findExtrema is applied on the 'unitized' (de-repeated) vector.
Second, extrema at the tails (the first and last elements of the vector) are often problematic, because for those data points, only one-sided comparisons are available. By default, findExtrema considers such endpoints as local minima/maxima if they are part of a plateau (i.e. if the endpoint is equal to its nearest neighbour). However, this behaviour can be changed by setting the argument 'tail' to "never" or "do_not_care".
Third, neighbours of a missing value are returned as missing values because if a given data window has at least one missing value, no minimum or maximum can be computed.

findExtrema returns an object of the same shape and length as x, recoding the original values in x to integer values 0, 1, 2, or NA, where 0 refers to data points which are neither minima nor maxima, 1 stands for local minima, 2 for local maxima, and NA for not available. Additionally, elements of constant vectors are coded by 3 as default, but can be any integer between 0 and 3 or NA.

Instead of setting 'global' to TRUE, you can also set 'n' large enough (e.g. length(x)) to achieve the same effect.

# create a vector with two local minima (which are equal) and two 
# local maxima (which are different)
x <- c(10, 7, -1, 6, 2, -1, 5, 4, 3)

# find local minima/maxima
(x_extr <- findExtrema(x))

# the same with a more stringent criterion
(x_extr2 <- findExtrema(x, 2L))

# return only the top 1 extrema; note that the local minima are equal,
# so both of them are returned, but only the higher local maximum is kept
(x_extr3 <- findExtrema(x, topN = 1L))

# findExtrema() always returns an integer vector or matrix
stopifnot(is.integer(x_extr))

# look for global extrema
(x_global <- findExtrema(x, global = TRUE))

# the same with large 'n'
(x_global2 <- findExtrema(x, length(x)))

# modify the vector to have a plateau at the start, and a missing value at
# the position 8; consider only the nearest neighbours
x <- c(10, x)
x[8] <- NA
x

# now the first two elements should also be identified as local maxima,
# but the second local minimum is not a local minimum any more because 
# there is a missing value in its neighbourhood
(x_extr <- findExtrema(x))

# visualize the results (blue: local minimum, red: local maximum)
plot(x, type = "l", lty = 3)
points(x, pch = 16, col = c("grey", "blue", "red")[findExtrema(x) + 1L])

# however, if 'tail' is set to "never", the first two elements are not
# extrema
(x_extr <- findExtrema(x, tail = "n"))

# how to treat constant vectors is ambiguous -> by default, findExtrema()
# assigns a special value (3L) to such data points, but this can be
# overridden
(x <- rep_len(10, 8))
findExtrema(x)
findExtrema(x, constant = 0)

# x can be a matrix (or even an array)
x <- cbind(sin(seq(0, 3*pi, pi/4)), cos(seq(0, 3*pi, pi/4)))
(x_extr <- findExtrema(x))
matplot(x, type = "l", lty = 3, col = 1)
points(x[, 1L], pch = 16, 
       col = c("grey", "blue", "red")[x_extr[, 1L] + 1L])
points(x[, 2L], pch = 16, 
       col = c("grey", "blue", "red")[x_extr[, 2L] + 1L])