List objects

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).

classes, methods

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 aconcreteclass (e.g. theGRangesListconstructor defined in theGenomicRangespackage), then the constructor function returns an instance of that class. If it's the name of avirtualclass (e.g. theListconstructor defined in this package, or theIntegerListorRleListorRangesListconstructors defined in theIRangespackage), 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 callas(x, "List"). This will typically yield an object from a subclass ofCompressedList.
  • Use ofextractList. This function, defined in theIRangespackage, extracts user-specified groups of elements from a vector-like object and returns them in a List (or sometimes list) object.


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).

See Also

  • List-utilsfor common operations on List objects.
  • Vectorobjects for the parent class.
  • TheSimpleListclass for a direct extension of the List class.
  • TheCompressedListclass defined in theIRangespackage for another direct extension of the List class.
  • TheIntegerList,RleList, andIRangesclasses and constructors defined in theIRangespackage for more examples of concrete List subclasses.
  • TheextractListfunction defined in theIRangespackage for grouping elements of a vector-like object into a list-like object.

  • 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
  • coerce,List,data.frame-method
  • [,List-method
  • [<-,List-method
  • [[,List-method
  • [[<-,List-method
  • $,List-method
  • $<-,List-method
  • show,List-method
showClass("List")  # shows (some of) the known subclasses
Documentation reproduced from package S4Vectors, version 0.10.1, License: Artistic-2.0

Community examples

Looks like there are no examples yet.