R: RLE utilities

rle.utils {statnet.common} | R Documentation

## RLE utilities

### Description

Simple utilities for operations on RLE-encoded vectors.

### Usage

    ## S3 method for class 'rle'
    c(...)

    ## S3 method for class 'rle'
    !x

    binop.rle(e1, e2, FUN)

    ## S3 method for class 'rle'
    e1 | e2

    ## S3 method for class 'rle'
    e1 & e2

    compact.rle(x)

    ## S3 method for class 'rle'
    any(..., na.rm = FALSE)

    ## S3 method for class 'rle'
    all(..., na.rm = FALSE)

    ## S3 method for class 'rle'
    e1 * e2

    ## S3 method for class 'rle'
    e1 / e2

    ## S3 method for class 'rle'
    e1 - e2

    ## S3 method for class 'rle'
    e1 + e2

    ## S3 method for class 'rle'
    e1 ^ e2

    ## S3 method for class 'rle'
    e1 %% e2

    ## S3 method for class 'rle'
    e1 %/% e2

    ## S3 method for class 'rle'
    e1 == e2

    ## S3 method for class 'rle'
    e1 > e2

    ## S3 method for class 'rle'
    e1 < e2

    ## S3 method for class 'rle'
    e1 != e2

    ## S3 method for class 'rle'
    e1 <= e2

    ## S3 method for class 'rle'
    e1 >= e2

    ## S3 method for class 'rle'
    sum(..., na.rm = FALSE)

    ## S3 method for class 'rle'
    mean(x, na.rm = FALSE, ...)

    ## S3 method for class 'rle'
    length(x)

    ## S3 method for class 'rle'
    is.na(x)

    ## S3 method for class 'rle'
    rep(x, ..., scale = c("element", "run"),
      doNotCompact = FALSE)

### Arguments

`...` | For `c`, objects to be concatenated. The first object must be of class `rle`. For `rep`, see documentation for `rep`. For `sum`, objects to be summed.
`x, e1, e2` | Arguments to unary (`x`) and binary (`e1` and `e2`) operators.
`FUN` | A binary function or operator or a name of one. It is assumed to be vectorized: it expects two vectors of equal lengths and outputs a vector of the same length.
`na.rm` | see documentation for `any`, `all`, and `sum`.
`scale` | whether to replicate the elements of the RLE-compressed vector or the runs.
`doNotCompact` | whether the method should call `compact.rle` the results before returning. Methods liable to produce very long output vectors, like `rep`, have this set `FALSE` by default.

### Value

Unless otherwise stated, all functions return an `rle` object. By default, the functions and the operators do not merge adjacent runs with the same value. This must be done explicitly with `compact.rle`.

`any`, `all`, `sum`, and `length` return logical, logical, numeric, and numeric vectors, respectively.

### Functions

- `binop.rle`: Perform an arbitrary binary operation on the pair of vectors represented by the `rle` objects.

- `compact.rle`: Compact the `rle` object by merging adjacent runs.

### Note

Since `rle` stores run lengths as integers, `compact.rle` will not merge runs that add up to lengths greater than what can be represented by a 32-bit signed integer (2147483647).

The `length` method returns the length of the vector represented by the object, obtained by summing the lengths of individual runs.

The `rep` method for `rle` objects is very limited at this time. Even though the default setting is to replicate elements of the vector, only the run-replicating functionality is implemented at this time except for the simplest case (scalar `times` argument).

### Examples

    x <- rle(as.logical(rbinom(10,1,.7)))
    y <- rle(as.logical(rbinom(10,1,.3)))

    stopifnot(isTRUE(all.equal(c(inverse.rle(x),inverse.rle(y)),inverse.rle(c(x,y)))))

    stopifnot(isTRUE(all.equal((!inverse.rle(x)),inverse.rle(!x))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)|inverse.rle(y)),inverse.rle(x|y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)&inverse.rle(y)),inverse.rle(x&y))))
    stopifnot(identical(rle(inverse.rle(x)&inverse.rle(y)),compact.rle(x&y)))

    big <- structure(list(lengths=as.integer(rep(.Machine$integer.max/4,6)),
                          values=rep(TRUE,6)), class="rle")

    stopifnot(all(aggregate(as.numeric(lengths)~values,
                            data=as.data.frame(unclass(big)),FUN=sum)
                  ==
                  aggregate(as.numeric(lengths)~values,
                            data=as.data.frame(unclass(compact.rle(big))),
                            FUN=sum)))

    x <- rle(as.logical(rbinom(10,1,.9)))
    y <- rle(as.logical(rbinom(10,1,.1)))

    stopifnot(isTRUE(all.equal(any(x),any(inverse.rle(x)))))
    stopifnot(isTRUE(all.equal(any(y),any(inverse.rle(y)))))

    stopifnot(isTRUE(all.equal(all(x),all(inverse.rle(x)))))
    stopifnot(isTRUE(all.equal(all(y),all(inverse.rle(y)))))

    x <- rle(sample(c(-1,+1), 10, c(.7,.3), replace=TRUE))
    y <- rle(sample(c(-1,+1), 10, c(.3,.7), replace=TRUE))

    stopifnot(isTRUE(all.equal((inverse.rle(x)*inverse.rle(y)),inverse.rle(x*y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)/inverse.rle(y)),inverse.rle(x/y))))
    stopifnot(isTRUE(all.equal((-inverse.rle(y)),inverse.rle(-y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)-inverse.rle(y)),inverse.rle(x-y))))
    stopifnot(isTRUE(all.equal((+inverse.rle(y)),inverse.rle(+y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)+inverse.rle(y)),inverse.rle(x+y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)^inverse.rle(y)),inverse.rle(x^y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)%%inverse.rle(y)),inverse.rle(x%%y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)%/%inverse.rle(y)),inverse.rle(x%/%y))))
    stopifnot(isTRUE(all.equal(inverse.rle(x)==inverse.rle(y),inverse.rle(x==y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)>inverse.rle(y)),inverse.rle(x>y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)<inverse.rle(y)),inverse.rle(x<y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)!=inverse.rle(y)),inverse.rle(x!=y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)<=inverse.rle(y)),inverse.rle(x<=y))))
    stopifnot(isTRUE(all.equal((inverse.rle(x)>=inverse.rle(y)),inverse.rle(x>=y))))

    stopifnot(isTRUE(all.equal(sum(inverse.rle(x)),sum(x))))
    stopifnot(isTRUE(all.equal(sum(inverse.rle(y)),sum(y))))

    stopifnot(isTRUE(all.equal(mean(inverse.rle(x)),mean(x))))
    stopifnot(isTRUE(all.equal(mean(inverse.rle(y)),mean(y))))

    stopifnot(isTRUE(all.equal(length(inverse.rle(x)),length(x))))
    stopifnot(isTRUE(all.equal(length(inverse.rle(y)),length(y))))

    x$values[1] <- NA
    y$values[1] <- NA
    stopifnot(isTRUE(all.equal(is.na(inverse.rle(x)),inverse.rle(is.na(x)))))
    stopifnot(isTRUE(all.equal(is.na(inverse.rle(y)),inverse.rle(is.na(y)))))

    x <- rle(sample(c(-1,+1), 10, c(.7,.3), replace=TRUE))
    y <- rpois(length(x$lengths), 2)

    stopifnot(isTRUE(all.equal(rep(inverse.rle(x), rep(y, x$lengths)),
                                   inverse.rle(rep(x, y, scale="run")))))

    stopifnot(isTRUE(all.equal(rep(inverse.rle(x), max(y)),
                                   inverse.rle(rep(x, max(y), scale="element")))))

[Package statnet.common version 4.2.0 Index]