TypedList-class {IRanges}R Documentation

Typed Lists

Description

The virtual class TypedList is an emulation of an ordinary list, except all of the elements must derive from a particular type. This is useful for validity checking and for implementing vectorized type-specific operations.

Details

In general, a TypedList may be treated as any ordinary list, except with regard to the element type restriction.

The required element type is indicated by the elementClass slot, a scalar string naming the class from which all elements must derive. This slot should never be set after initialization.

TypedList is a virtual class, so a subclass must be derived for a particular element type. This turns out to be useful in almost all cases, as the explicit class can be used as the type of a slot in a class that requires a homogeneous list of elements. Also, methods may be implemented for the subclass that, for example, perform a vectorized operation specific to the element type. Using this approach, the convention is for the prototype of the subclass to set the elementClass slot and to leave it unchanged.

Object Updating

updateTypedObject(object): Updates instances of objects the inherit from an older TypedList class definition to match the current TypedList class definition.

Subsetting

In the following code snippets, x is a TypedList object.

x[i]: Get a subset of x containing the elements indexed by i, which may be numeric, character, logical, NULL or missing. The behavior is very similar to an ordinary list, except operations that would insert NULL elements are only allowed if NULL is a valid element type.
x[[i]]: Get the element in x indexed by i, which may be a scalar number or string. The behavior is nearly identical to that of an ordinary list.
x$name: similar to above, where name is taken literally as an element name.
x[[i]] <- value: Replace the element at index i (a scalar number or string) with value. The behavior is very similar to that of an ordinary list, except value must be coercible (and is coerced) to the required element class.
x$name <- value: similar to above, where name is taken literally as an element name.

Accessors

In the following code snippets, x is a TypedList object.

length(x): Get the number of elements in x
names(x), names(x) <- value: Get or set the names of the elements in the list. This behaves exactly the same as an ordinary list.
elementClass(x): Get the scalar string naming the class from which all elements must derive.
elementLengths(x): Get the 'length' of each of the elements.
isEmpty(x): Gets a logical vector indicating which elements are empty.

Splitting and Combining

The following are methods for combining TypedList elements. In the signatures, x is a TypedList object.

append(x, values, after = length(x)): Insert the TypedList values onto x at the position given by after. values must have an elementClass that extends that of x.
c(x, ..., recursive = FALSE): Appends the TypedList objects in ... onto the end of x. All arguments must have an element class that extends that of x.

Note that the default split method happens to work on TypedList objects.

Coercion

In the following code snippets, x is a TypedList object.

as.list(x), as(from, "list"): Coerces a TypedList to an ordinary list. Note that this is preferred over the elements accessor for getting a list of the elements.
unlist(x): Combines all of the elements in this list into a single element via the c function and returns the result. Will not work if the elements have no method for c. Returns NULL if there are no elements in x, which may not be what is expected in many cases. Subclasses should implement their own logic.

Looping

lapply(X, FUN, ...): Like the standard lapply function defined in the base package, the lapply method for TypedLike objects returns a list of the same length as X, each element of which is the result of applying FUN to the corresponding element of X.
sapply(X, FUN, ..., simplify=TRUE, USE.NAMES=TRUE): Like the standard sapply function defined in the base package, the sapply method for TypedList objects is a user-friendly version of lapply by default returning a vector or matrix if appropriate.

Author(s)

Michael Lawrence

See Also

ListLike, RangesList for an example implementation

Examples

  ## demonstrated on IntegerList objects, as TypedList is virtual

  int1 <- c(1L,2L,3L,5L,2L,8L)
  int2 <- c(15L,45L,20L,1L,15L,100L,80L,5L)
  collection <- IntegerList(int1, int2)

  ## names
  names(collection) <- c("one", "two")
  names(collection)
  names(collection) <- NULL # clear names
  names(collection)
  names(collection) <- "one"
  names(collection) # c("one", NA)

  ## extraction
  collection[[1]] # range1
  collection[["1"]] # NULL, does not exist
  collection[["one"]] # range1
  collection[[NA_integer_]] # NULL

  ## subsetting
  collection[numeric()] # empty
  collection[NULL] # empty
  collection[] # identity
  collection[c(TRUE, FALSE)] # first element
  collection[2] # second element
  collection[c(2,1)] # reversed
  collection[-1] # drop first
  collection$one

  ## replacement
  collection$one <- int2
  collection[[2]] <- int1

  ## combining
  col1 <- IntegerList(one = int1, int2)
  col2 <- IntegerList(two = int2, one = int1)
  col3 <- IntegerList(int2)
  append(col1, col2)
  append(col1, col2, 0)
  c(col1, col2, col3)

  ## get the mean for each element
  lapply(col1, mean)

[Package IRanges version 1.2.0 Index]