as.hi: Hybrid Index, coercion to

In OHDSI/ff: Memory-Efficient Storage of Large Data on Disk and Fast Access Functions

Description

The generic as.hi and its methods are the main (internal) means for preprocessing index information into the hybrid index class hi. Usually as.hi is called transparently from [.ff. However, you can explicitely do the index-preprocessing, store the Hybrid Index hi, and use the hi for subscripting.

Usage

as.hi(x, ...)
## S3 method for class 'hi'
as.hi(x, ...)
## S3 method for class 'ri'
as.hi(x, maxindex = length(x), ...)
## S3 method for class 'bit'
as.hi(x, range = NULL, maxindex = length(x), vw = NULL
, dim = NULL, dimorder = NULL, pack = TRUE, ...)
## S3 method for class 'bitwhich'
as.hi(x, maxindex = length(x), pack = FALSE, ...)
## S3 method for class 'call'
as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL, vw = NULL
, vw.convert = TRUE, pack = TRUE, envir = parent.frame(), ...)
## S3 method for class 'name'
as.hi(x, envir = parent.frame(), ...)

## S3 method for class 'integer'
as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL
, symmetric = FALSE, fixdiag = NULL, vw = NULL, vw.convert = TRUE
, dimorder.convert  = TRUE, pack = TRUE, NAs = NULL, ...)
## S3 method for class 'which'
as.hi(x, ...)
## S3 method for class 'double'
as.hi(x, ...)
## S3 method for class 'logical'
as.hi(x, maxindex = NA, dim = NULL, vw = NULL, pack = TRUE, ...)
## S3 method for class 'character'
as.hi(x, names, vw = NULL, vw.convert = TRUE, ...)
## S3 method for class 'matrix'
as.hi(x, dim, dimorder = NULL, symmetric = FALSE, fixdiag = NULL
, vw = NULL, pack = TRUE, ...)

Arguments

x	an appropriate object of the class for which we dispatched
envir	the environment in which to evaluate components of the index expression
maxindex	maximum positive indexposition maxindex, is needed with negative indices, if vw or dim is given, maxindex is calculated automatically
names	the names of the indexed vector for character indexing
dim	the dim of the indexed matrix to be stored within the hi object
dimorder	the dimorder of the indexed matrix to be stored within the hi object, may convert interpretation of x
symmetric	the symmetric of the indexed matrix to be stored within the hi object
fixdiag	the fixdiag of the indexed matrix to be stored within the hi object
vw	the virtual window vw of the indexed vector or matrix to be stored within the hi object, see details
vw.convert	FALSE to prevent doubly virtual window conversion, this is needed for some internal calls that have done the virtual window conversion already, see details
dimorder.convert	FALSE to prevent doubly dimorder conversion, this is needed for some internal calls that have done the dimorder conversion already, see details
NAs	a vector of NA positions to be stored rlepacked, not fully supported yet
pack	FALSE to prevent rlepacking, note that this is a hint rather than a guarantee, as.hi.bit might ignore this
range	NULL or a vector with two elements indicating first and last position to be converted from 'bit' to 'hi'
...	further argument passed from generic to method or from wrapper method to as.hi.integer

Details

The generic dispatches appropriately, as.hi.hi returns an hi object unchanged, as.hi.call tries to hiparse instead of evaluate its input in order to save RAM. If parsing is successfull as.hi.call will ignore its argument pack and always pack unless the subscript is too small to do so. If parsing fails it evaluates the index expression and dispatches again to one of the other methods. as.hi.name and as.hi.( are wrappers to as.hi.call. as.hi.integer is the workhorse for coercing evaluated expressions and as.hi.which is a wrapper removing the which class attribute. as.hi.double, as.hi.logical and as.hi.character are also wrappers to as.hi.integer, but note that as.hi.logical is not memory efficient because it expands all positions and then applies logical subscripting.
as.hi.matrix calls arrayIndex2vectorIndex and then as.hi.integer to interpret and preprocess matrix indices.
If the dim and dimorder parameter indicate a non-standard dimorder (dimorderStandard), the index information in x is converted from a standard dimorder interpretation to the requested dimorder.
If the vw parameter is used, the index information in x is interpreted relative to the virtual window but stored relative to the abolute origin. Back-coercion via as.integer.hi and friends will again return the index information relative to the virtual window, thus retaining symmetry and transparency of the viurtual window to the user.
You can use length to query the index length (possibly length of negative subscripts), poslength to query the number of selected elements (even with negative subscripts), and maxindex to query the largest possible index position (within virtual window, if present)
Duplicated negative indices are removed and will not be recovered by as.integer.hi.

Value

an object of class hi

Note

Avoid changing the Hybrid Index representation, this might crash the [.ff subscripting.

Author(s)

Jens Oehlschl?gel

See Also

hi for the Hybrid Index class, hiparse for parsing details, as.integer.hi for back-coercion, [.ff for ff subscripting

Examples

  message("integer indexing with and without rel-packing")
  as.hi(1:12)
  as.hi(1:12, pack=FALSE)
  message("if index is double, the wrapper method just converts to integer")
  as.hi(as.double(1:12))
  message("if index is character, the wrapper method just converts to integer")
  as.hi(c("a","b","c"), names=letters)
  message("negative index must use maxindex (or vw)")
  as.hi(-(1:3), maxindex=12)
  message("logical index can use maxindex")
  as.hi(c(FALSE, FALSE, TRUE, TRUE))
  as.hi(c(FALSE, FALSE, TRUE, TRUE), maxindex=12)

  message("matrix index")
  x <- matrix(1:12, 6)
  as.hi(rbind(c(1,1), c(1,2), c(2,1)), dim=dim(x))

  message("first ten positions within virtual window")
  i <- as.hi(1:10, vw=c(10, 80, 10))
  i
  message("back-coerce relativ to virtual window")
  as.integer(i)
  message("back-coerce relativ to absolute origin")
  as.integer(i, vw.convert=FALSE)

  message("parsed index expressions save index RAM")
    as.hi(quote(1:1000000000))
## Not run: 
  message("compare to RAM requirement when the index experssion is evaluated")
    as.hi(1:1000000000)

## End(Not run)

message("example of parsable index expression")
  a <- seq(100, 200, 20)
  as.hi(substitute(c(1:5, 4:9, a)))
  hi(c(1,4, 100),c(5,9, 200), by=c(1,1,20))

message("two examples of index expression temporarily expanded to full length due to 
non-supported use of brackets '(' and mathematical operators '+' accepting token")
message("example1: accepted token but aborted parsing because length>16")
  as.hi(quote(1+(1:16)))
message("example1: rejected token and aborted parsing because length>16")
  as.hi(quote(1+(1:17)))

OHDSI/ff documentation built on May 7, 2019, 8:30 p.m.