is: Test logical statements on data points
In tdeenes/eegR: Analyze EEG Signals

Description Usage Arguments Details Functions Use cases See Also Examples

is* are functions which produce functions of class IsFunction to test logical statements on each data point of an atomic object (vector, matrix, or array). See Details for the general idea, Functions for the short function-specific descriptions and the section Use cases for short examples.

isPattern(
  pattern.,
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isEqual(
  ref.,
  tol. = .Machine$double.eps^0.5,
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isSame(
  ref.,
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isBetween(
  lwr. = -Inf,
  upr. = Inf,
  open. = c("none", "both", "lwr", "upr"),
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isNegative(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isPositive(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isExtremum(
  what. = c("both", "min", "max"),
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isLocalMaximum(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isLocalMinimum(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isMaximum(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

isMinimum(
  strict. = TRUE,
  negate. = FALSE,
  subset. = list(),
  expand. = list(),
  options. = list()
)

`pattern.`	a character regexp pattern, see the 'pattern' argument in `grepl`
`strict.`	logical value whether the tested condition is obligatory (TRUE, the default) or optional (FALSE). Only used for combining multiple tests (not available at the moment).
`negate.`	logical value whether the return value of the function should be negated (default: FALSE). You can also use the standard `!` operator for negation which has a specific method for the `IsFunction` class (see Examples).
`subset., expand.`	a named list of character, numeric, or logical vectors or a subsetting function (of class IsFunction) indicating which levels of which dimensions to subset or expand on (see Details). If an unnamed list, it must have an attribute 'dim_index', referring to the numeric indices of the dimensions to subset or expand on. Use it only if you are absolutely sure about the datasets you want to test later on!
`options.`	a list of further arguments passed to the wrapped function (see Functions for details)
`ref.`	the reference value or a vector (or matrix/array) of reference values.
`tol.`	tolerance value, the maximum difference which is still tolerated. Can be a vector (or matrix/array) as well.
`lwr., upr.`	numeric values referring to the lower and upper limit (the defaults are -Inf and Inf, respectively). Both lwr. and upr. can be scalars and vectors as well.
`open.`	the side of the interval which is open (that is, it does not contain the given endpoint); can be "none" (the default), "both", lwr" or "upr"
`what.`	specifies whether minima ("min"), maxima ("max") or extrema ("both", the default) should be tested

All is* functions return a function of the class IsFunction which has only one argument, 'x' (the data object to test). 'x' can be an atomic vector, matrix, or array; all other object types result in error.
A second major rule is that all functions returned by an is* function return a logical object of the same shape as the input object. The third rule is that the function returned by any is* function is a hard (strict) or soft (optional) constraint, controled by the 'strict.' argument. This affects the way how the results are combined for joint logical tests (see combine).
Additionally, all is* functions has 'negate.', 'subset.', and 'expand.' arguments. By setting 'negate.' to TRUE, the function can be conceived of as a not* function. The same can be achieved by using the standard negation operator (see Examples).
The 'subset.' and 'expand.' arguments are only considered if the returned function will be called on matrices or arrays. If 'subset.' is provided, the logical condition is tested only on the subsetted slice of the array, and all other data points in the array become FALSE (or TRUE, if negate. is TRUE). The 'expand.' argument does the same except that it expands the subsetted results to the original array instead of fixing the outer-subset data points to FALSE (or TRUE). See Examples.

isPattern: produces a function to test whether the values in an atomic character object match a pre-specified character pattern. See grepl for further details and additional arguments.
isEqual: produces a function to test whether the values in an atomic object are equal to a (vector of) reference value(s) with a given tolerance. The returned function accepts objects of any type for which as.Numeric does not fail (see the documentation of as.Numeric).
isSame: produces a function to test whether the values in an atomic object are the same as a (vector of) reference value(s). It is a wrapper around ==. If you want to test numeric values, isEqual is a much better alternative.
isBetween: produces a function to test whether the values in an atomic object are between pre-specified limits. The returned function accepts objects of any type for which as.Numeric does not fail (see the documentation of as.Numeric).
isNegative: produces a function to test whether the values in an atomic object are negative. The returned function accepts objects of any type for which as.Numeric does not fail (see the documentation of as.Numeric).
isPositive: produces a function to test whether the values in an atomic object are positive. The returned function accepts objects of any type for which as.Numeric does not fail (see the documentation of as.Numeric).
isExtremum: produces a function to test whether the the values in an atomic object are local or global extrema. See findExtrema for additional details and further arguments. The returned function accepts objects of any type for which as.Numeric does not fail (see the documentation of as.Numeric).
isLocalMaximum: a shorthand for isExtremum("max", ...). See findExtrema for additional details and further arguments.
isLocalMinimum: a shorthand for isExtremum("min", ...). See findExtrema for additional details and further arguments.
isMaximum: a shorthand for isExtremum("max", global = TRUE, ...). See findExtrema for additional details and further arguments.
isMinimum: a shorthand for isExtremum("min", global = TRUE, ...). See findExtrema for additional details and further arguments.

`is*` as simple pre-defined test

A very basic use case is to pre-define a logical rule and apply it to several objects. For example one can define
rangeTest <- isBetween(200, 300)
and use this rule to check for whatever numeric or numeric-like character vector, matrix or array whether the values are between 200 and 300. If x denotes the object, rangeTest(x) returns a logical object of the same length and shape as x with TRUEs for values between 200 and 300 and FALSE otherwise.

`is*` as function argument

is* functions come in especially handy if they are used as function arguments.
For example the code subsetArray(erps, time = isBetween(200, 300)) is a very compact and readable way of subsetting the erps data array on its time dimension, selecting only that part of the array where time >= 200 & time <= 300. Note that this allows the definition of a subsetting rule without knowing in advance how the object which is to be subsetted looks like. For example you can define sub_def <- isBetween(200, 300) beforehand and use sub_def as an argument in subsetArray for all data arrays if all of them have a time dimension measured in the same unit (note that the resolution and the time range may be different).

combine how to combine is* tests, and isStrict how to check afterwards whether a test is strict or optional

#
# example for isPattern #
#
# note how we pass the 'ignore.case' argument to the internally used
# grepl() function (see ?grepl)
check_start_a <- isPattern("^a", options. = list(ignore.case = TRUE))
check_start_a(c("a", "A", "ba"))

#
# example for isEqual #
#
check_zero <- isEqual(0, tol. = 1e-4)
check_zero(c("0", "0.000001", "1"))


# note that just like for other is* functions, the reference and the
# tolerance can be vectors (or even matrices or arrays), not only scalars,
# and its values are recycled or cropped if necessarily to match the length
# of the 'x' object
check_values <- isEqual(c(0, 1, 2))
check_values(c(0, 1.1, 2, 1e-9))



# it is also possible to base the check only on a subset of x and also
# on a reference slice of x which is then expanded back to the original
# array;
# here we want to test that in the "pre-test" phase of an experiment which
# observations had a width of 1 with 0.1 tolerance (expanded also to height)
check_width <- isEqual(1, tol. = 0.1,
                       subset. = list(time = "pre"),
                       expand. = list(measure = "width")
                       )
( x <- array(c(1.001, 1.6, 1.2, 1.003, 1.01, 1, 4, 3.5),
             dim = c(2, 2, 2),
             dimnames = list(observation = c("a", "b"),
                             measure = c("width", "height"),
                             time = c("pre", "post"))) )
( res <- check_width(x) )

# note that all "time = post" data points are FALSE, and also that
# all height measures are TRUE where width is TRUE
array(paste(x, res, sep = ": "), dim(x), dimnames(x))


# isEqual, just like all other is* functions, can be negated:
check_not_zero <- isEqual(0, negate. = TRUE)
check_not_zero(1)


# the same can be achieved by using ! for negation
check_not_zero2 <- !isEqual(0)
check_not_zero2(1)

#
# example for isSame #
#
check_not_A <- isSame("A", negate. = TRUE)
check_not_A(c("a", "A"))

#
# example for isBetween() #
#
# note that lwr. and upr. might be given in reversed order
check_0_100 <- isBetween(100, 0)
check_0_100(c(-1, 1, 101))

#
# example for isExtremum #
#
# note how we can pass the 'global' and 'tail' arguments to the internal
# findExtrema() function (see ?findExtrema)
check_global_extr <- isExtremum(options. = list(global = TRUE, 
                                                tail = "do_not_care"))
check_global_extr(c(-1, 1, 0, 100, 50))