XVector objects

Description

The XVector virtual class is a general container for storing an "external vector". It inherits from the Vector class, which has a rich interface.

The following classes derive directly from the XVector class:

The XRaw class is a container for storing an "external raw vector" i.e. an external sequence of bytes (stored as char values at the C level).

The XInteger class is a container for storing an "external integer vector" i.e. an external sequence of integer values (stored as int values at the C level).

The XDouble class is a container for storing an "external double vector" i.e. an external sequence of numeric values (stored as double values at the C level).

Also the XString class defined in the Biostrings package.

The purpose of the X* containers is to provide a "pass by address" semantic and also to avoid the overhead of copying the sequence data when a linear subsequence needs to be extracted.

Additional Subsetting operations on XVector objects

In the code snippets below, x is an XVector object.

subseq(x, start=NA, end=NA, width=NA): Extract the subsequence from x specified by start, end and width. The supplied start/end/width values are solved by a call to solveUserSEW(length(x), start=start, end=end, width=width) and therefore must be compliant with the rules of the SEW (Start/End/Width) interface (see ?solveUserSEW for the details).

A note about performance: subseq does NOT copy the sequence data of an XVector object. Hence it's very efficient and is therefore the recommended way to extract a linear subsequence (i.e. a set of consecutive elements) from an XVector object. For example, extracting a 100Mb subsequence from Human chromosome 1 (a 250Mb DNAString object) with subseq is (almost) instantaneous and has (almost) no memory footprint (the cost in time and memory does not depend on the length of the original sequence or on the length of the subsequence to extract).

subseq(x, start=NA, end=NA, width=NA) <- value: Replace the subsequence specified on the left (i.e. the subsequence in x specified by start, end and width) by value. value must belong to the same class as x, or to one of its subclasses, or must be NULL. This replacement method can modify the length of x, depending on how the length of the left subsequence compares to the length of value. It can be used for inserting elements in x (specify an empty left subsequence for this) or deleting elements from x (use a NULL right value for this). Unlike the extraction method above, this replacement method always copies the sequence data of x (even for XVector objects). NOTE: Only works for XRaw (and derived) objects for now.

Author(s)

H. Pag<c3><83><c2><a8>s

See Also

Vector-class, DNAString-class, XVectorList-class, Views-class, solveUserSEW, compact

Examples

  ## ---------------------------------------------------------------------
  ## A. XRaw OBJECTS
  ## ---------------------------------------------------------------------

  x1 <- XRaw(4)  # values are not initialized
  x1
  x2 <- as(c(255, 255, 199), "XRaw")
  x2
  y <- c(x1, x2, NULL, x1)  # NULLs are ignored
  y
  subseq(y, start=-4)
  subseq(y, start=-4) <- x2
  y

  ## ---------------------------------------------------------------------
  ## B. XInteger OBJECTS
  ## ---------------------------------------------------------------------

  x3 <- XInteger(12, val=c(-1:10))
  x3
  length(x3)

  ## Subsetting
  x4 <- XInteger(99999, val=sample(99, 99999, replace=TRUE) - 50)
  x4
  subseq(x4, start=10)
  subseq(x4, start=-10)
  subseq(x4, start=-20, end=-10)
  subseq(x4, start=10, width=5)
  subseq(x4, end=10, width=5)
  subseq(x4, end=10, width=0)

  x3[length(x3):1]
  x3[length(x3):1, drop=FALSE]

Results

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(XVector)
Loading required package: BiocGenerics
Loading required package: parallel

Attaching package: 'BiocGenerics'

The following objects are masked from 'package:parallel':

    clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
    clusterExport, clusterMap, parApply, parCapply, parLapply,
    parLapplyLB, parRapply, parSapply, parSapplyLB

The following objects are masked from 'package:stats':

    IQR, mad, xtabs

The following objects are masked from 'package:base':

    Filter, Find, Map, Position, Reduce, anyDuplicated, append,
    as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
    get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
    match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
    rbind, rownames, sapply, setdiff, sort, table, tapply, union,
    unique, unsplit

Loading required package: S4Vectors
Loading required package: stats4

Attaching package: 'S4Vectors'

The following objects are masked from 'package:base':

    colMeans, colSums, expand.grid, rowMeans, rowSums

Loading required package: IRanges
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/XVector/XVector-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: XVector-class
> ### Title: XVector objects
> ### Aliases: class:XVector XVector-class XVector length,XVector-method
> ###   c,XVector-method [,XVector-method subseq subseq<-
> ###   subseq,XVector-method subseq<-,XVector-method
> ###   as.numeric,XVector-method show,XVector-method
> ###   ==,XVector,XVector-method class:XRaw XRaw-class XRaw
> ###   coerce,raw,XRaw-method coerce,raw,XVector-method
> ###   coerce,numeric,XRaw-method as.raw,XRaw-method as.integer,XRaw-method
> ###   as.vector,XRaw-method class:XInteger XInteger-class XInteger
> ###   coerce,numeric,XInteger-method coerce,integer,XVector-method
> ###   as.integer,XInteger-method as.vector,XInteger-method class:XDouble
> ###   XDouble-class XDouble XNumeric coerce,numeric,XDouble-method
> ###   coerce,numeric,XVector-method as.numeric,XDouble-method
> ###   as.vector,XDouble-method show,XDouble-method
> ### Keywords: methods classes
> 
> ### ** Examples
> 
>   ## ---------------------------------------------------------------------
>   ## A. XRaw OBJECTS
>   ## ---------------------------------------------------------------------
> 
>   x1 <- XRaw(4)  # values are not initialized
>   x1
XRaw of length 4
 [1] 1 0 0 0
>   x2 <- as(c(255, 255, 199), "XRaw")
>   x2
XRaw of length 3
 [1] 255 255 199
>   y <- c(x1, x2, NULL, x1)  # NULLs are ignored
>   y
XRaw of length 11
 [1]   1   0   0   0 255 255 199   1   0   0   0
>   subseq(y, start=-4)
XRaw of length 4
 [1] 1 0 0 0
>   subseq(y, start=-4) <- x2
>   y
XRaw of length 10
 [1]   1   0   0   0 255 255 199 255 255 199
> 
>   ## ---------------------------------------------------------------------
>   ## B. XInteger OBJECTS
>   ## ---------------------------------------------------------------------
> 
>   x3 <- XInteger(12, val=c(-1:10))
>   x3
XInteger of length 12
 [1] -1  0  1  2  3  4  5  6  7  8  9 10
>   length(x3)
[1] 12
> 
>   ## Subsetting
>   x4 <- XInteger(99999, val=sample(99, 99999, replace=TRUE) - 50)
>   x4
XInteger of length 99999
 [1] -49  27 -24 -33   7 -41  28  18  11 ...  30   0 -28 -24 -46  49  -5  35 -16
>   subseq(x4, start=10)
XInteger of length 99990
 [1]  14   8  14 -45 -11  18   4 -46   4 ...  30   0 -28 -24 -46  49  -5  35 -16
>   subseq(x4, start=-10)
XInteger of length 10
 [1] -23  30   0 -28 -24 -46  49  -5  35 -16
>   subseq(x4, start=-20, end=-10)
XInteger of length 11
 [1]   8  17  -6  17 -38 -13  19  -6   4  12 -23
>   subseq(x4, start=10, width=5)
XInteger of length 5
 [1]  14   8  14 -45 -11
>   subseq(x4, end=10, width=5)
XInteger of length 5
 [1] -41  28  18  11  14
>   subseq(x4, end=10, width=0)
XInteger of length 0
> 
>   x3[length(x3):1]
XInteger of length 12
 [1] 10  9  8  7  6  5  4  3  2  1  0 -1
>   x3[length(x3):1, drop=FALSE]
XInteger of length 12
 [1] 10  9  8  7  6  5  4  3  2  1  0 -1
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>