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,
RangesList,
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 RangesList
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).
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.
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.
as.env(x, enclos = parent.frame()):
Creates an environment from x with 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.
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 RangesList.
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<c3><83><c2><a8>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
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(S4Vectors)
Loading required package: stats4
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
Attaching package: 'S4Vectors'
The following objects are masked from 'package:base':
colMeans, colSums, expand.grid, rowMeans, rowSums
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/S4Vectors/List-class.Rd_%03d_medium.png", width=480, height=480)
> ### Name: List-class
> ### Title: List objects
> ### Aliases: class:List List-class List elementType elementType,List-method
> ### elementType,vector-method elementNROWS elementNROWS,ANY-method
> ### elementNROWS,List-method elementLengths elementLengths,ANY-method
> ### isEmpty isEmpty,ANY-method isEmpty,List-method relistToClass
> ### relistToClass,ANY-method coerce,List,list-method
> ### coerce,ANY,List-method coerce,integer,List-method as.list,List-method
> ### as.env,List-method unlist,List-method as.data.frame,List-method
> ### coerce,List,data.frame-method [,List-method [<-,List-method
> ### [[,List-method [[<-,List-method $,List-method $<-,List-method
> ### show,List-method
> ### Keywords: methods classes
>
> ### ** Examples
>
> showClass("List") # shows (some of) the known subclasses
Virtual Class "List" [package "S4Vectors"]
Slots:
Name: elementType elementMetadata metadata
Class: character DataTableORNULL list
Extends:
Class "Vector", directly
Class "Annotated", by class "Vector", distance 2
Known Subclasses:
Class "SimpleList", directly
Class "HitsList", by class "SimpleList", distance 2
Class "SelfHitsList", by class "HitsList", distance 3
Class "SortedByQueryHitsList", by class "HitsList", distance 3
Class "SortedByQuerySelfHitsList", by class "SelfHitsList", distance 4
Class "FilterRules", by class "SimpleList", distance 2
>
>
>
>
>
> dev.off()
null device
1
>