IRanges and NormalIRanges objects

Description

The IRanges class is a simple implementation of the Ranges container where 2 integer vectors of the same length are used to store the start and width values. See the Ranges virtual class for a formal definition of Ranges objects and for their methods (all of them should work for IRanges objects).

Some subclasses of the IRanges class are: NormalIRanges, Views, etc...

A NormalIRanges object is just an IRanges object that is guaranteed to be "normal". See the Normality section in the man page for Ranges objects for the definition and properties of "normal" Ranges objects.

Constructor

See ?`IRanges-constructor`.

Coercion

as(from, "IRanges"): Creates an IRanges instance from a Ranges object, logical vector, or integer vector. When from is a logical vector, the resulting IRanges object contains the indices for the runs of TRUE values. When from is an integer vector, the elements are either singletons or "increase by 1" sequences.

as(from, "NormalIRanges"): Creates a NormalIRanges instance from a logical or integer vector. When from is an integer vector, the elements must be strictly increasing.

Combining

c(x, ..., .ignoreElementMetadata=TRUE) Combining IRanges objects is straightforward when they do not have any elementMetadata set. If only one of the IRanges object has its elementMetadata set, this is also trivial: the resulting (combined) IRanges object will take the single elementMetadata as the default, and set the corresponding elementMetadata for the other IRanges object to NA. When multiple IRanges object have their own elementMetadata, the user must ensure that each such linkS4class{DataFrame} have identical layouts to each other (same columns defined), in order for the combination to be successful, otherwise an error will be thrown. The user can call c(x, ..., .ignoreElementMetadata=TRUE) in order to combine IRanges objects with differing elementMetadata, which will result in the combined object having NO elementMetadata defined.

Methods for NormalIRanges objects

max(x): The maximum value in the finite set of integers represented by x.

min(x): The minimum value in the finite set of integers represented by x.

Author(s)

H. Pages

See Also

Ranges-class, Ranges-utils, IRanges-constructor, IRanges-utils, IRanges-setops.

Some direct subclasses of the IRanges class (other than NormalIRanges): Views-class.

Examples

  showClass("IRanges")  # shows (some of) the known subclasses

  ## ---------------------------------------------------------------------
  ## A. MANIPULATING IRanges OBJECTS
  ## ---------------------------------------------------------------------
  ## All the methods defined for Ranges objects work on IRanges objects.
  ## See ?Ranges for some examples.
  ## Also see ?`IRanges-utils` and ?`IRanges-setops` for additional
  ## operations on IRanges objects.
  
  ## Combining IRanges objects
  ir1 <- IRanges(c(1, 10, 20), width=5)
  elementMetadata(ir1) <- DataFrame(score=runif(3))
  ir2 <- IRanges(c(101, 110, 120), width=10)
  elementMetadata(ir2) <- DataFrame(score=runif(3))
  ir3 <- IRanges(c(1001, 1010, 1020), width=20)
  elementMetadata(ir3) <- DataFrame(value=runif(3))
  some.iranges <- c(ir1, ir2)
  ## all.iranges <- c(ir1, ir2, ir3) ## This will raise an error
  all.iranges <- c(ir1, ir2, ir3, .ignoreElementMetadata=TRUE)
  stopifnot(is.null(elementMetadata(all.iranges)))

  ## ---------------------------------------------------------------------
  ## B. A NOTE ABOUT PERFORMANCE
  ## ---------------------------------------------------------------------
  ## Using an IRanges object for storing a big set of ranges is more
  ## efficient than using a standard R data frame:
  N <- 2000000L  # nb of ranges
  W <- 180L      # width of each range
  start <- 1L
  end <- 50000000L
  set.seed(777)
  range_starts <- sort(sample(end-W+1L, N))
  range_widths <- rep.int(W, N)
  ## Instantiation is faster
  system.time(x <- IRanges(start=range_starts, width=range_widths))
  system.time(y <- data.frame(start=range_starts, width=range_widths))
  ## Subsetting is faster
  system.time(x16 <- x[c(TRUE, rep.int(FALSE, 15))])
  system.time(y16 <- y[c(TRUE, rep.int(FALSE, 15)), ])
  ## Internal representation is more compact
  object.size(x16)
  object.size(y16)