List-class {S4Vectors} | R Documentation

## List objects

### Description

List objects are Vector objects with a `"[["`, `elementType` and `elementNROWS` method. The List class serves a similar role as list in base R.

It adds one slot, the `elementType` slot, to the two slots shared by all Vector objects.

The `elementType` slot is the preferred location for List subclasses to store the type of data represented in the sequence. It is designed to take a character of length 1 representing the class of the sequence elements. While the List class performs no validity checking based on `elementType`, if a subclass expects elements to be of a given type, that subclass is expected to perform the necessary validity checking. For example, the subclass IntegerList (defined in the IRanges package) has `elementType = "integer"` and its validity method checks if this condition is TRUE.

To be functional, a class that inherits from List must define at least a `"[["` method (in addition to the minimum set of Vector methods).

### Construction

List objects are typically constructed using one of the 3 following methods:

- Use of a constructor function. Many constructor functions are provided for List objects e.g. `List`, `IntegerList`, `RleList`, `IntegerRangesList`, `GRangesList`, etc... Which one to use depends on the particular type of List object to construct. The name of a constructor function is always the name of a valid class. If it's the name of a concrete class (e.g. the `GRangesList` constructor defined in the GenomicRanges package), then the constructor function returns an instance of that class. If it's the name of a virtual class (e.g. the `List` constructor defined in this package, or the `IntegerList` or `RleList` or `IntegerRangesList` constructors defined in the IRanges package), then the returned object belongs to a concrete subclass of that virtual class. Which subclass exactly depends on each constructor function (see man page of a particular constructor function for the details).

- Coercion to List or to a List subclass. Many coercion methods are provided to turn any object into a List object. One general and convenient way to convert any vector-like object into a List is to call `as(x, "List")`. This will typically yield an object from a subclass of CompressedList.

- Use of `extractList`. This function, defined in the IRanges package, extracts user-specified groups of elements from a vector-like object and returns them in a List (or sometimes list) object.

### Accessors

In the following code snippets, `x` is a List object.

  `length(x)`: Get the number of list elements in `x`.

  `names(x)`, `names(x) <- value`: Get or set the names of the elements in the List.

  `mcols(x, use.names=FALSE)`, `mcols(x) <- value`: Get or set the metadata columns. See Vector man page for more information.

  `elementType(x)`: Get the scalar string naming the class from which all elements must derive.

  `elementNROWS(x)`: Get the length (or nb of row for a matrix-like object) of each of the elements. Equivalent to `sapply(x, NROW)`.

  `isEmpty(x)`: Returns a logical indicating either if the sequence has no elements or if all its elements are empty.

### Coercion

To List.

  `as(x, "List")`: Converts a vector-like object into a List, usually a CompressedList derivative. One notable exception is when `x` is an ordinary list, in which case `as(x, "List")` returns a SimpleList derivative.

  To explicitly request a SimpleList derivative, call `as(x, "SimpleList")`.

  See `?CompressedList` (you might need to load the IRanges package first) and `?SimpleList` for more information about the CompressedList and SimpleList representations.

From List. In the code snippets below, `x` is a List object.

  `as.list(x, ...)`, `as(from, "list")`: Turns `x` into an ordinary list.

  `unlist(x, recursive=TRUE, use.names=TRUE)`: Concatenates the elements of `x` into a single vector-like object (of class `elementType(x)`).

  `as.data.frame(x, row.names=NULL, optional=FALSE , value.name="value", use.outer.mcols=FALSE, group_name.as.factor=FALSE, ...)`: Coerces a `List` to a `data.frame`. The result has the same length as unlisted `x` with two additional columns, `group` and `group_name`. `group` is an `integer` that indicates which list element the record came from. `group_name` holds the list name associated with each record; value is `character` by default and `factor` when `group_name.as.factor` is TRUE.

  When `use.outer.mcols` is TRUE the metadata columns on the outer list elements of `x` are replicated out and included in the `data.frame`. List objects that unlist to a single vector (column) are given the column name 'value' by default. A custom name can be provided in `value.name`.

  Splitting values in the resulting `data.frame` by the original groups in `x` should be done using the `group` column as the `f` argument to `splitAsList`. To relist data, use `x` as the `skeleton` argument to `relist`.

### Subsetting

In the code snippets below, `x` is a List object.

  `x[i]`: Return a new List object made of the list elements selected by subscript `i`. Subscript `i` can be of any type supported by subsetting of a Vector object (see Vector man page for the details), plus the following types: IntegerList, LogicalList, CharacterList, integer-RleList, logical-RleList, character-RleList, and IntegerRangesList. Those additional types perform subsetting within the list elements rather than across them.

  `x[i] <- value`: Replacement version of `x[i]`.

  `x[[i]]`: Return the selected list element `i`, where `i` is an numeric or character vector of length 1.

  `x[[i]] <- value`: Replacement version of `x[[i]]`.

  `x$name`, `x$name <- value`: Similar to `x[[name]]` and `x[[name]] <- value`, but `name` is taken literally as an element name.

### relistToClass

`relistToClass(x)` is the opposite of `elementType(y)` in the sense that the former returns the class of the result of relisting (or splitting) `x` while the latter returns the class of the result of unlisting (or unsplitting) `y`. More formally, if `x` is an object that is relistable and `y` a list-like object:

        relistToClass(x) is class(relist(x, some_skeleton))
        elementType(y) is class(unlist(y))

As a consequence, for any object `x` for which `relistToClass(x)` is defined and returns a valid class, `elementType(new(relistToClass(x)))` should return `class(x)`.

### Author(s)

P. Aboyoun and H. Pagès

### See Also

- List-utils for common operations on List objects.

- Vector objects for the parent class.

- The SimpleList class for a direct extension of the List class.

- The CompressedList class defined in the IRanges package for another direct extension of the List class.

- The IntegerList, RleList, and IRanges classes and constructors defined in the IRanges package for more examples of concrete List subclasses.

- The extractList function defined in the IRanges package for grouping elements of a vector-like object into a list-like object.

### Examples

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

[Package S4Vectors version 0.22.1 Index]