optimal.index: creating standardized, memory optimized index for subsetting

In ref: References for R

Description

Function optimal.index converts an index specification of type {logical, integer, -integer, character} into one of {integer, -integer} whatever is smaller. Function need.index returns TRUE if the index does represent a subset (and thus indexing is needed). Function posi.index returns positive integers representing the (sub)set.

Usage

optimal.index(i, n=length(i.names), i.names = names(i), i.previous = NULL, strict = TRUE)
need.index(oi)
posi.index(oi)

Arguments

i	the original one-dimensional index
n	length of the indexed dimension (potential iMax if i where integer), not necessary if names= is given
i.names	if i is character then names= represents the names of the indexed dimension
i.previous	if i.previous= is given, the returned index represents x[i.previous][i] == x[optimal.index] rather than x[i] == x[optimal.index]
strict	set to FALSE to allow for NAs and duplicated index values, but see details
oi	a return value of optimal.index

Details

When strict=TRUE it is expected that i does not contain NAs and no duplicated index values. Then identical(x[i], x[optimal.index(i, n=length(x), i.names=names(x))$i]) == TRUE .
When strict=FALSE i may contain NAs and/or duplicated index values. In this case length optimisation is not performed and optimal.index always returns positive integers.

Value

optimal.index returns the index oi with attributes n=n and ni=length(x[optimal.index]) (which is n-length(i) when i is negative). need.index returns a logical scalar posi.index returns a vector of positive integers (or integer(0))

Note

need.index(NULL) is defined and returns FALSE. This allows a function to have an optional parameter oi=NULL and to determine the need of subsetting in one reqest.

Author(s)

Jens Oehlschl<e4>gel

See Also

refdata
please ignore the following unpublished links: ids2index, shift.index, startstop2index

Examples

  l <- letters
  names(l) <- letters
  stopifnot({i <- 1:3 ; identical(l[i], l[optimal.index(i, n=length(l))])})
  stopifnot({i <- -(4:26) ; identical(l[i], l[optimal.index(i, n=length(l))])})
  stopifnot({i <- c(rep(TRUE, 3), rep(FALSE, 23)) 
    identical(l[i], l[optimal.index(i, n=length(l))])})
  stopifnot({i <- c("a", "b", "c")
    identical(l[i], l[optimal.index(i, i.names=names(l))])})
  old.options <- options(show.error.messages=FALSE)
    stopifnot(inherits(try(optimal.index(c(1:3, 3), n=length(l))), "try-error"))
  options(old.options)
  stopifnot({i <- c(1:3, 3, NA)
    identical(l[i], l[optimal.index(i, n=length(l), strict=FALSE)])})
  stopifnot({i <- c(-(4:26), -26)
    identical(l[i], l[optimal.index(i, n=length(l), strict=FALSE)])})
  stopifnot({i <- c(rep(TRUE, 3), rep(FALSE, 23), TRUE, FALSE, NA)
    identical(l[i], l[optimal.index(i, n=length(l), strict=FALSE)])})
  stopifnot({i <- c("a", "b", "c", "a", NA)
    identical(l[i], l[optimal.index(i, i.names=names(l), strict=FALSE)])})
  rm(l)

ref documentation built on May 2, 2019, 6:08 p.m.