CompressedList-class: CompressedList objects

In Bioconductor/IRanges: Foundation of integer range manipulation in Bioconductor

CompressedList objects

Description

Like the SimpleList class defined in the S4Vectors package, the CompressedList class extends the List virtual class.

Details

Unlike the SimpleList class, CompressedList is virtual, that is, it cannot be instantiated. Many concrete (i.e. non-virtual) CompressedList subclasses are defined and documented in this package (e.g. CompressedIntegerList, CompressedCharacterList, CompressedRleList, etc...), as well as in other packages (e.g. GRangesList in the GenomicRanges package, GAlignmentsList in the GenomicAlignments package, etc...). It's easy for developers to extend CompressedList to create a new CompressedList subclass and there is generally very little work involved to make this new subclass fully operational.

In a CompressedList object the list elements are concatenated together in a single vector-like object. The partitioning of this single vector-like object (i.e. the information about where each original list element starts and ends) is also kept in the CompressedList object. This internal representation is generally more memory efficient than SimpleList, especially if the object has many list elements (e.g. thousands or millions). Also it makes it possible to implement many basic list operations very efficiently.

Many objects like LogicalList, IntegerList, CharacterList, RleList, etc... exist in 2 flavors: CompressedList and SimpleList. Each flavor is incarnated by a concrete subclass: CompressedLogicalList and SimpleLogicalList for virtual class LogicalList, CompressedIntegerList and SimpleIntegerList for virtual class IntegerList, etc... It's easy to switch from one representation to the other with as(x, "CompressedList") and as(x, "SimpleList"). Also the constructor function for those virtual classes have a switch that lets the user choose the representation at construction time e.g. CharacterList(..., compress=TRUE) or CharacterList(..., compress=FALSE). See below for more information.

Constructor

See the List man page in the S4Vectors package for a quick overview of how to construct List objects in general.

Unlike for SimpleList objects, there is no CompressedList constructor function.

However, many constructor functions for List derivatives provide the compress argument that lets the user choose between the CompressedList and SimpleList representations at construction time. For example, depending on whether the compress argument of the CharacterList() constructor is set to TRUE or FALSE, a CompressedCharacterList or SimpleCharacterList instance will be returned.

Finally let's mention that the most efficient way to construct a CompressedList derivative is with

    relist(unlisted, partitioning)

where unlisted is a vector-like object and partitioning a PartitioningByEnd object describing a partitioning of unlisted. The cost of this relist operation is virtually zero because unlisted and partitioning get stored as-is in the returned object.

Accessors

Same as for List objects. See the List man page in the S4Vectors package for more information.

Coercion

All the coercions documented in the List man page apply to CompressedList objects.

Subsetting

Same as for List objects. See the List man page for more information.

Looping and functional programming

Same as for List objects. See ?`List-utils` in the S4Vectors package for more information.

Displaying

When a CompressedList object is displayed, the "Compressed" prefix is removed from the real class name of the object. See classNameForDisplay in the S4Vectors package for more information about this.

See Also

• List in the S4Vectors package for an introduction to List objects and their derivatives (CompressedList is a direct subclass of List which makes CompressedList objects List derivatives).

• The SimpleList class defined and documented in the S4Vectors package for an alternative to CompressedList.

• relist and extractList for efficiently constructing a List derivative from a vector-like object.

• The CompressedNumericList class for an example of a concrete CompressedList subclass.

• PartitioningByEnd objects. These objects are used inside CompressedList derivatives to keep track of the partitioning of the single vector-like object made of all the list elements concatenated together.

Examples

## Fastest way to construct a CompressedList object:
unlisted <- runif(12)
partitioning <- PartitioningByEnd(c(5, 5, 10, 12), names=LETTERS[1:4])
partitioning

x1 <- relist(unlisted, partitioning)
x1

stopifnot(identical(lengths(partitioning), lengths(x1)))

## Note that the class of the CompressedList derivative returned by
## relist() is determined by relistToClass():
relistToClass(unlisted)
stopifnot(relistToClass(unlisted) == class(x1))

## Displaying a CompressedList object:
x2 <- IntegerList(11:12, integer(0), 3:-2, compress=TRUE)
class(x2)

## The "Simple" prefix is removed from the real class name of the
## object:
x2

## This is controlled by internal helper classNameForDisplay():
classNameForDisplay(x2)
classNameForDisplay(x1)

Bioconductor/IRanges documentation built on Dec. 7, 2024, 1:19 p.m.