It adds one slot, the
elementType slot, to the two slots shared by
all Vector objects.
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
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
"[[" method (in addition to the minimum set of Vector
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.
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
GRangesListconstructor 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
Listconstructor defined in this package, or the
RangesListconstructors 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
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.
In the following code snippets,
x is a List object.
length(x): Get the number of list elements in
names(x) <- value: Get or set the names of the elements in the List.
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
elementLengths(x): Equivalent to
elementNROWS(x). Clearly a misnomer. Will be deprecated soon.
isEmpty(x): Returns a logical indicating either if the sequence has no elements or if all its elements are empty.
as(x, "List"): Converts a vector-like object into a List, usually a CompressedList derivative. One notable exception is when
xis 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
?SimpleListfor more information about the CompressedList and SimpleList representations.
xis a List object.
as(from, "list"): Turns
xinto an ordinary list.
unlist(x, recursive=TRUE, use.names=TRUE): Concatenates the elements of
xinto a single vector-like object (of class
as.data.frame(x, row.names=NULL, optional=FALSE , value.name="value", use.outer.mcols=FALSE, group_name.as.factor=FALSE, ...): Coerces a
data.frame. The result has the same length as unlisted
xwith two additional columns,
integerthat indicates which list element the record came from.
group_nameholds the list name associated with each record; value is
characterby default and
group_name.as.factoris TRUE. When
use.outer.mcolsis TRUE the metadata columns on the outer list elements of
xare 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.frameby the original groups in
xshould be done using the
groupcolumn as the
splitAsList. To relist data, use
as.env(x, enclos = parent.frame()): Creates an environment from
xwith a symbol for each
names(x). The values are not actually copied into the environment. Rather, they are dynamically bound using
makeActiveBinding. This prevents unnecessary copying of the data from the external vectors into R vectors. The values are cached, so that the data is not copied every time the symbol is accessed.
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
ican 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 RangesList. Those additional types perform subsetting within the list elements rather than across them.
x[i] <- value: Replacement version of
x[[i]]: Return the selected list element
iis an numeric or character vector of length 1.
x[[i]] <- value: Replacement version of
x$name <- value: Similar to
x[[name]] <- value, but
nameis taken literally as an element name.
relistToClass(x) is the opposite of
elementType(y) in the
sense that the former returns the class of the result of relisting (or
x while the latter returns the class of the result of
unlisting (or unsplitting)
More formally, if
x is an object that is relistable and
a list-like object:
relistToClass(x) is class(relist(x, some_skeleton)) elementType(y) is class(unlist(y))As a consequence, for any object
relistToClass(x)is defined and returns a valid class,
- 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
- The extractList function defined in the IRanges package for grouping elements of a vector-like object into a list-like object.
showClass("List") # shows (some of) the known subclasses