Subsetting a vector-like object

As with ordinary R atomic vectors, it is often necessary to subset one sequence from another. When this subsetting does not duplicate or reorder the elements being extracted, the result is called a subsequence. In general, the [ function can be used to construct a new sequence or extract a subsequence, but its interface is often inconvenient and not amenable to optimization. To compensate for this, the S4Vectors package supports seven additional functions for sequence extraction:

1.window - Extracts a subsequence over a specified region.

2.subset - Extracts the subsequence specified by a logical vector.

3.head - Extracts a consecutive subsequence containing the first n elements.

4.tail - Extracts a consecutive subsequence containing the last n elements.

5.rev - Creates a new sequence with the elements in the reverse order.

6.rep - Creates a new sequence by repeating sequence elements.

The following code illustrates how these functions are used on an Rle vector:

xSnippet <- window(xRle, 4751, 4760)
xSnippet

## integer-Rle of length 10 with 9 runs
##   Lengths: 1 1 1 1 1 1 1 1 2
##   Values : 4 6 5 4 6 2 6 7 5

head(xSnippet)

## integer-Rle of length 6 with 6 runs
##   Lengths: 1 1 1 1 1 1
##   Values : 4 6 5 4 6 2

tail(xSnippet)

## integer-Rle of length 6 with 5 runs
##   Lengths: 1 1 1 1 2
##   Values : 6 2 6 7 5

rev(xSnippet)

## integer-Rle of length 10 with 9 runs
##   Lengths: 2 1 1 1 1 1 1 1 1
##   Values : 5 7 6 2 6 4 5 6 4

rep(xSnippet, 2)

## integer-Rle of length 20 with 18 runs
##   Lengths: 1 1 1 1 1 1 1 1 2 1 1 1 1 1 1 1 1 2
##   Values : 4 6 5 4 6 2 6 7 5 4 6 5 4 6 2 6 7 5

subset(xSnippet, xSnippet >= 5L)

## integer-Rle of length 7 with 5 runs
##   Lengths: 1 1 2 1 2
##   Values : 6 5 6 7 5

Concatenating vector-like objects

The S4Vectors package uses two generic functions, c and append, for concatenating two Vector derivatives. The methods for Vector objects follow the definition that these two functions are given the base package.

c(xSnippet, rev(xSnippet))

## integer-Rle of length 20 with 17 runs
##   Lengths: 1 1 1 1 1 1 1 1 4 1 1 1 1 1 1 1 1
##   Values : 4 6 5 4 6 2 6 7 5 7 6 2 6 4 5 6 4

append(xSnippet, xSnippet, after=3)

## integer-Rle of length 20 with 18 runs
##   Lengths: 1 1 1 1 1 1 1 1 1 1 1 2 1 1 1 1 1 2
##   Values : 4 6 5 4 6 5 4 6 2 6 7 5 4 6 2 6 7 5

Looping over subsequences of vector-like objects

In R, for looping can be an expensive operation. To compensate for this, the S4Vectors package provides aggregate and shiftApply methods (shiftApply is a new generic function defined in S4Vectors to perform calculations over subsequences of vector-like objects.

The aggregate function combines sequence extraction functionality of the window function with looping capabilities of the sapply function. For example, here is some code to compute medians across a moving window of width 3 using the function aggregate:

xSnippet

## integer-Rle of length 10 with 9 runs
##   Lengths: 1 1 1 1 1 1 1 1 2
##   Values : 4 6 5 4 6 2 6 7 5

aggregate(xSnippet, start=1:8, width=3, FUN=median)

## [1] 5 5 5 4 6 6 6 5

The shiftApply function is a looping operation involving two vector-like objects whose elements are lined up via a positional shift operation. For example, the elements of xRle and yRle were simulated from Poisson distributions with the mean of element i from yRle being equivalent to the mean of element i + 250 from xRle. If we did not know the size of the shift, we could estimate it by finding the shift that maximizes the correlation between xRle and yRle.

cor(xRle, yRle)

## [1] 0.5739224

shifts <- seq(235, 265, by=3)
corrs  <- shiftApply(shifts, yRle, xRle, FUN=cor)

plot(shifts, corrs)

Correlation between xRle and yRle for various shifts

The result is shown in Fig.@ref(fig:figshiftcorrs)

More on Rle objects

When there are lots of consecutive repeats, the memory savings through an RLE can be quite dramatic. For example, the xRle object occupies less than one third of the space of the original xVector object, while storing the same information:

as.vector(object.size(xRle) / object.size(xVector))

## [1] 0.3020726

identical(as.vector(xRle), xVector)

## [1] TRUE

The functions runValue and runLength extract the run values and run lengths from an Rle object respectively:

head(runValue(xRle))

## [1] 0 1 0 1 0 1

head(runLength(xRle))

## [1]  780    1  208    1 1599    1

The Rle class supports many of the basic methods associated with R atomic vectors including the Ops, Math, Math2, Summary, and Complex group generics. Here is a example of manipulating Rle objects using methods from the Ops group:

xRle > 0

## logical-Rle of length 10000000 with 197127 runs
##   Lengths:   780     1   208     1  1599 ...     5     1    91     1   927
##   Values : FALSE  TRUE FALSE  TRUE FALSE ... FALSE  TRUE FALSE  TRUE FALSE

xRle + yRle

## integer-Rle of length 10000000 with 1957707 runs
##   Lengths: 780   1 208   1  13   1 413   1 ...   1   5   1  91   1 507   1 419
##   Values :   0   1   0   1   0   1   0   1 ...   2   0   1   0   1   0   1   0

xRle > 0 | yRle > 0

## logical-Rle of length 10000000 with 210711 runs
##   Lengths:   780     1   208     1    13 ...    91     1   507     1   419
##   Values : FALSE  TRUE FALSE  TRUE FALSE ... FALSE  TRUE FALSE  TRUE FALSE

Here are some from the Summary group:

range(xRle)

## [1]  0 26

sum(xRle > 0 | yRle > 0)

## [1] 2105185

And here is one from the Math group:

log1p(xRle)

## numeric-Rle of length 10000000 with 1510219 runs
##   Lengths:      780        1      208        1 ...       91        1      927
##   Values : 0.000000 0.693147 0.000000 0.693147 ... 0.000000 0.693147 0.000000

As with atomic vectors, the cor and shiftApply functions operate on Rle objects:

cor(xRle, yRle)

## [1] 0.5739224

shiftApply(249:251, yRle, xRle,
           FUN=function(x, y) {var(x, y) / (sd(x) * sd(y))})

## [1] 0.8519138 0.8517324 0.8517725

For more information on the methods supported by the Rle class, consult the Rle man page.