\HeaderA{Sequence-class}{Sequence objects}{Sequence.Rdash.class}
\aliasA{"!=,Sequence,Sequence-method}{Sequence-class}{"!=,Sequence,Sequence.Rdash.method}
\aliasA{\$,Sequence-method}{Sequence-class}{.Rdol.,Sequence.Rdash.method}
\aliasA{aggregate,data.frame-method}{Sequence-class}{aggregate,data.frame.Rdash.method}
\aliasA{aggregate,matrix-method}{Sequence-class}{aggregate,matrix.Rdash.method}
\aliasA{aggregate,Sequence-method}{Sequence-class}{aggregate,Sequence.Rdash.method}
\aliasA{aggregate,ts-method}{Sequence-class}{aggregate,ts.Rdash.method}
\aliasA{aggregate,vector-method}{Sequence-class}{aggregate,vector.Rdash.method}
\aliasA{append,Sequence,Sequence-method}{Sequence-class}{append,Sequence,Sequence.Rdash.method}
\aliasA{as.env}{Sequence-class}{as.env}
\aliasA{as.env,Sequence-method}{Sequence-class}{as.env,Sequence.Rdash.method}
\aliasA{as.list,Sequence-method}{Sequence-class}{as.list,Sequence.Rdash.method}
\aliasA{c,Sequence-method}{Sequence-class}{c,Sequence.Rdash.method}
\aliasA{class:Sequence}{Sequence-class}{class:Sequence}
\aliasA{coerce,Sequence,list-method}{Sequence-class}{coerce,Sequence,list.Rdash.method}
\aliasA{elementLengths}{Sequence-class}{elementLengths}
\aliasA{elementLengths,CompressedList-method}{Sequence-class}{elementLengths,CompressedList.Rdash.method}
\aliasA{elementLengths,list-method}{Sequence-class}{elementLengths,list.Rdash.method}
\aliasA{elementLengths,Sequence-method}{Sequence-class}{elementLengths,Sequence.Rdash.method}
\aliasA{elementMetadata}{Sequence-class}{elementMetadata}
\aliasA{elementMetadata,Sequence-method}{Sequence-class}{elementMetadata,Sequence.Rdash.method}
\aliasA{elementMetadata<\Rdash}{Sequence-class}{elementMetadata<.Rdash.}
\aliasA{elementMetadata<-,Sequence-method}{Sequence-class}{elementMetadata<.Rdash.,Sequence.Rdash.method}
\aliasA{elementType}{Sequence-class}{elementType}
\aliasA{elementType,Sequence-method}{Sequence-class}{elementType,Sequence.Rdash.method}
\aliasA{elementType,vector-method}{Sequence-class}{elementType,vector.Rdash.method}
\aliasA{endoapply,Sequence-method}{Sequence-class}{endoapply,Sequence.Rdash.method}
\aliasA{eval,expressionORlanguage,Sequence-method}{Sequence-class}{eval,expressionORlanguage,Sequence.Rdash.method}
\aliasA{Filter,ANY,Sequence-method}{Sequence-class}{Filter,ANY,Sequence.Rdash.method}
\aliasA{Find,ANY,Sequence-method}{Sequence-class}{Find,ANY,Sequence.Rdash.method}
\aliasA{head,Sequence-method}{Sequence-class}{head,Sequence.Rdash.method}
\aliasA{isEmpty}{Sequence-class}{isEmpty}
\aliasA{isEmpty,ANY-method}{Sequence-class}{isEmpty,ANY.Rdash.method}
\aliasA{lapply,Sequence-method}{Sequence-class}{lapply,Sequence.Rdash.method}
\aliasA{Map}{Sequence-class}{Map}
\aliasA{Map,Sequence-method}{Sequence-class}{Map,Sequence.Rdash.method}
\aliasA{mapply}{Sequence-class}{mapply}
\aliasA{mapply,Sequence-method}{Sequence-class}{mapply,Sequence.Rdash.method}
\aliasA{mendoapply,Sequence-method}{Sequence-class}{mendoapply,Sequence.Rdash.method}
\aliasA{nlevels,Sequence-method}{Sequence-class}{nlevels,Sequence.Rdash.method}
\aliasA{NROW,Sequence-method}{Sequence-class}{NROW,Sequence.Rdash.method}
\aliasA{Position,ANY,Sequence-method}{Sequence-class}{Position,ANY,Sequence.Rdash.method}
\aliasA{Reduce,ANY,Sequence-method}{Sequence-class}{Reduce,ANY,Sequence.Rdash.method}
\aliasA{rep,Sequence-method}{Sequence-class}{rep,Sequence.Rdash.method}
\aliasA{rep.int}{Sequence-class}{rep.int}
\aliasA{rep.int,Sequence-method}{Sequence-class}{rep.int,Sequence.Rdash.method}
\aliasA{rev,Sequence-method}{Sequence-class}{rev,Sequence.Rdash.method}
\aliasA{sapply,Sequence-method}{Sequence-class}{sapply,Sequence.Rdash.method}
\aliasA{seqselect}{Sequence-class}{seqselect}
\aliasA{seqselect,factor-method}{Sequence-class}{seqselect,factor.Rdash.method}
\aliasA{seqselect,NULL-method}{Sequence-class}{seqselect,NULL.Rdash.method}
\aliasA{seqselect,Sequence-method}{Sequence-class}{seqselect,Sequence.Rdash.method}
\aliasA{seqselect,vector-method}{Sequence-class}{seqselect,vector.Rdash.method}
\aliasA{seqselect<\Rdash}{Sequence-class}{seqselect<.Rdash.}
\aliasA{seqselect<-,factor-method}{Sequence-class}{seqselect<.Rdash.,factor.Rdash.method}
\aliasA{seqselect<-,Sequence-method}{Sequence-class}{seqselect<.Rdash.,Sequence.Rdash.method}
\aliasA{seqselect<-,vector-method}{Sequence-class}{seqselect<.Rdash.,vector.Rdash.method}
\aliasA{Sequence}{Sequence-class}{Sequence}
\aliasA{shiftApply}{Sequence-class}{shiftApply}
\aliasA{shiftApply,Sequence,Sequence-method}{Sequence-class}{shiftApply,Sequence,Sequence.Rdash.method}
\aliasA{shiftApply,vector,vector-method}{Sequence-class}{shiftApply,vector,vector.Rdash.method}
\aliasA{stack,Sequence-method}{Sequence-class}{stack,Sequence.Rdash.method}
\aliasA{subset,Sequence-method}{Sequence-class}{subset,Sequence.Rdash.method}
\aliasA{tail,Sequence-method}{Sequence-class}{tail,Sequence.Rdash.method}
\aliasA{tapply,Sequence-method}{Sequence-class}{tapply,Sequence.Rdash.method}
\aliasA{values}{Sequence-class}{values}
\aliasA{values,Sequence-method}{Sequence-class}{values,Sequence.Rdash.method}
\aliasA{values<\Rdash}{Sequence-class}{values<.Rdash.}
\aliasA{values<-,Sequence-method}{Sequence-class}{values<.Rdash.,Sequence.Rdash.method}
\aliasA{window,factor-method}{Sequence-class}{window,factor.Rdash.method}
\aliasA{window,NULL-method}{Sequence-class}{window,NULL.Rdash.method}
\aliasA{window,Sequence-method}{Sequence-class}{window,Sequence.Rdash.method}
\aliasA{window,vector-method}{Sequence-class}{window,vector.Rdash.method}
\aliasA{window<-,factor-method}{Sequence-class}{window<.Rdash.,factor.Rdash.method}
\aliasA{window<-,Sequence-method}{Sequence-class}{window<.Rdash.,Sequence.Rdash.method}
\aliasA{window<-,vector-method}{Sequence-class}{window<.Rdash.,vector.Rdash.method}
\aliasA{with,Sequence-method}{Sequence-class}{with,Sequence.Rdash.method}
\aliasA{[,Sequence-method}{Sequence-class}{[,Sequence.Rdash.method}
\aliasA{[<-,Sequence-method}{Sequence-class}{[<.Rdash.,Sequence.Rdash.method}
\aliasA{[[,Sequence-method}{Sequence-class}{[[,Sequence.Rdash.method}
\keyword{methods}{Sequence-class}
\keyword{classes}{Sequence-class}
\begin{Description}\relax
The Sequence virtual class serves as the heart of the IRanges package
and has over 90 subclasses. It serves a similar role as \LinkA{Annotated}{Annotated.Rdash.class} class), and
\code{elementMetadata}. Their purpose is defined below.

The \code{elementType} slot is the preferred location for Sequence
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 Sequence class performs no validity checking
based on \code{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 \LinkA{IntegerList}{IntegerList} has
\code{elementType = "integer"} and its validity method checks if this
condition is TRUE.

The Sequence class supports the storage of global and element-wise metadata
with its \code{metadata} and \code{elementMetadata} slots. The
\code{metadata} slot can store a list of metadata pertaining to the whole
object and the \code{elementMetadata} slot can store a
\LinkA{DataTable}{DataTable.Rdash.class} (or \code{NULL}) for element-wise metadata with a
row for each element and a column for each metadata variable.

To be functional, a class that inherits from Sequence must define a
\code{length} and \code{names} methods as well as one or both of the
subscript methods \code{"[["} and \code{"["}.
\end{Description}
\begin{Section}{Accessors}
In the following code snippets, \code{x} is a Sequence object.

\describe{
\item[] \code{length(x)}:
Get the number of elements in \code{x}.

\item[] \code{NROW(x)}:
Defined as \code{length(x)} for any Sequence object that is
\emph{not} a \LinkA{DataTable}{DataTable.Rdash.class} object.
If \code{x} is a \LinkA{DataTable}{DataTable.Rdash.class} object, then it's
defined as \code{nrow(x)}.

\item[] \code{names(x)}, \code{names(x) <- value}:
Get or set the names of the elements in the Sequence.

\item[] \code{elementType(x)}:
Get the scalar string naming the class from which all elements must
derive.

\item[] \code{elementLengths(x)}:
Get the 'length' of each of the elements.

\item[] \code{isEmpty(x)}:
Returns a logical indicating either if the sequence has no elements
or if all its elements are empty.

\item[] \code{nlevels(x)}:
Returns the number of factor levels.

\item[] \code{metadata(x)}, \code{metadata(x) <- value}:
Get or set the list holding arbitrary R objects as annotations.
May be, and often is, empty.

\item[] \code{elementMetadata(x), elementMetadata(x) <- value}:
Get or set the \LinkA{DataTable}{DataTable.Rdash.class} holding local metadata on each
element. The rows are named according to the names of the elements.
Optional, may be \code{NULL}.

\item[] \code{values(x), values(x) <- value}:
Alternative to \code{elementMetadata} functions.

}
\end{Section}
\begin{Section}{Subsetting}
In the code snippets below, \code{x} is a Sequence object or regular R vector
object. The R vector object methods for \code{window} and \code{seqselect}
are defined in this package and the remaining methods are defined in base R.

\describe{
\item[] \code{x[i, drop=TRUE]}:
If defined, returns a new Sequence object made of selected elements
\code{i}, which can be missing; an NA-free logical, numeric, or
character vector; or a logical Rle object. The \code{drop} argument
specifies whether or not to coerce the returned sequence to a standard
vector.

\item[] \code{x[i] <- value}:
Equivalent to \code{seqselect(x, i) <- value}.

\item[] \code{window(x, start = NA, end = NA, width = NA, frequency = NULL, delta = NULL, ...)}:
Extract the subsequence window from the Sequence object using:
\describe{
\item[\code{start}, \code{end}, \code{width}] The start, end, or width
of the window. Two of the three are required.
\item[\code{frequency}, \code{delta}] Optional arguments that specify
the sampling frequency and increment within the window.
}
In general, this is more efficient than using \code{"["} operator.

\item[] \code{window(x, start = NA, end = NA, width = NA, keepLength = TRUE) <- value}:
Replace the subsequence window specified on the left (i.e. the subsequence
in \code{x} specified by \code{start}, \code{end} and \code{width})
by \code{value}.
\code{value} must either be of class \code{class(x)}, belong to a subclass
of \code{class(x)}, be coercible to \code{class(x)}, or be \code{NULL}.
If \code{keepLength} is \code{TRUE}, the elements of \code{value} are
repeated to create a Sequence with the same number of elements as the
width of the subsequence window it is replacing.
If \code{keepLength} is \code{FALSE}, this replacement method can modify
the length of \code{x}, depending on how the length of the left
subsequence window compares to the length of \code{value}.

\item[] \code{seqselect(x, start=NULL, end=NULL, width=NULL)}:
Similar to \code{window}, except that multiple consecutive subsequences
can be requested for concatenation. As such two of the three \code{start},
\code{end}, and \code{width} arguments can be used to specify the
consecutive subsequences. Alternatively, \code{start} can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle. If the concatenation of
the consecutive subsequences is undesirable, consider using
\code{\LinkA{Views}{Views}}.

\item[] \code{seqselect(x, start=NULL, end=NULL, width=NULL) <- value}:
Similar to \code{window<-}, except that multiple consecutive subsequences
can be replaced by a \code{value} whose length is a divisor of the number
of elements it is replacing. As such two of the three \code{start},
\code{end}, and \code{width} arguments can be used to specify the
consecutive subsequences. Alternatively, \code{start} can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle.

\item[] \code{head(x, n = 6L)}:
If \code{n} is non-negative, returns the first n elements of the Sequence
object.
If \code{n} is negative, returns all but the last \code{abs(n)} elements
of the Sequence object.

\item[] \code{tail(x, n = 6L)}:
If \code{n} is non-negative, returns the last n elements of the Sequence
object.
If \code{n} is negative, returns all but the first \code{abs(n)} elements
of the Sequence object.

\item[] \code{rev(x)}:
Return a new Sequence object made of the original elements in the reverse
order.

\item[] \code{rep(x, times, length.out, each)}, \code{rep.int(x, times)}:
Repeats the values in \code{x} through one of the following conventions:
\describe{
\item[\code{times}] Vector giving the number of times to repeat each
element if of length \code{length(x)}, or to repeat the whole vector
if of length 1.
\item[\code{length.out}] Non-negative integer. The desired length of
the output vector.
\item[\code{each}] Non-negative integer.  Each element of \code{x} is
repeated \code{each} times.
}

\item[] \code{subset(x, subset)}:
Return a new Sequence object made of the subset using logical vector
\code{subset}, where missing values are taken as FALSE.

}
\end{Section}
\begin{Section}{Element extraction (list style)}
In the code snippets below, \code{x} is a Sequence object.

\describe{
\item[] \code{x[[i]]}:
If defined, return the selected element \code{i}, where \code{i} is an
numeric or character vector of length 1.

\item[] \code{x\$name}:
Similar to \code{x[[name]]}, but \code{name} is taken literally as an
element name.

}
\end{Section}
\begin{Section}{Combining}
In the code snippets below, \code{x} is a Sequence object.

\describe{
\item[] \code{c(x, ...)}:
Combine \code{x} and the Sequence objects in \code{...} together.
Any object in \code{...} must belong to the same class as \code{x},
or to one of its subclasses, or must be \code{NULL}.
The result is an object of the same class as \code{x}.

\item[] \code{append(x, values, after = length(x))}: Insert the
\code{Sequence} \code{values} onto \code{x} at the position given by
\code{after}. \code{values} must have an \code{elementType} that extends
that of \code{x}.

}
\end{Section}
\begin{Section}{Looping}
In the code snippets below, \code{x} is a Sequence object.

\describe{
\item[] \code{lapply(X, FUN, ...)}:
Like the standard \code{\LinkA{lapply}{lapply}} function defined in the
base package, the \code{lapply} method for Sequence objects returns
a list of the same length as \code{X}, with each element being the
result of applying \code{FUN} to the corresponding element of \code{X}.

\item[] \code{sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)}:
Like the standard \code{\LinkA{sapply}{sapply}} function defined in the
base package, the \code{sapply} method for Sequence objects is a
user-friendly version of \code{lapply} by default returning a vector
or matrix if appropriate.

\item[] \code{mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)}:
Like the standard \code{\LinkA{mapply}{mapply}} function defined in the
base package, the \code{mapply} method for Sequence objects is a
multivariate version of \code{sapply}.

\item[] \code{tapply(X, INDEX, FUN = NULL, ..., simplify = TRUE)}:
Like the standard \code{\LinkA{tapply}{tapply}} function defined in the
base package, the \code{tapply} method for Sequence objects applies a
function to each cell of a ragged array, that is to each (non-empty)
group of values given by a unique combination of the levels of certain
factors.

\item[] \code{endoapply(X, FUN, ...)}:
Similar to \code{\LinkA{lapply}{lapply}}, but performs an endomorphism,
i.e. returns an object of \code{class(X)}.

\item[] \code{mendoapply(FUN, ..., MoreArgs = NULL)}:
Similar to \code{\LinkA{mapply}{mapply}}, but performs an endomorphism
across multiple objects, i.e. returns an object of
\code{class(list(...)[[1]])}.

\item[] \code{shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE, verbose = FALSE)}:
Let \code{i} be the indices in \code{SHIFT},
\code{X\_i = window(X, 1 + OFFSET, length(X) - SHIFT[i])}, and
\code{Y\_i = window(Y, 1 + SHIFT[i], length(Y) - OFFSET)}. Calculates
the set of \code{FUN(X\_i, Y\_i, ...)} values and return the results in a
convenient form:
\describe{
\item[\code{SHIFT}] A non-negative integer vector of shift values.
\item[\code{X}, \code{Y}] The Sequence or R vector objects to shift.
\item[\code{FUN}] The function, found via \code{match.fun}, to be
applied to each set of shifted vectors.
\item[\dots] Further arguments for \code{FUN}.
\item[OFFSET] A non-negative integer offset to maintain throughout
the shift operations.
\item[\code{simplify}] A logical value specifying whether or not the
result should be simplified to a vector or matrix if possible.
\item[\code{verbose}] A logical value specifying whether or not to
print the \code{i} indices to track the iterations.
}

\item[] \code{aggregate(x, by, FUN, start = NULL, end = NULL, width = NULL,
                      frequency = NULL, delta = NULL, ..., simplify = TRUE))}:
Generates summaries on the specified windows and returns the result in a
convenient form:
\describe{
\item[\code{by}] An object with \code{start}, \code{end}, and
\code{width} methods.
\item[\code{FUN}] The function, found via \code{match.fun}, to be
applied to each window of \code{x}.
\item[\code{start}, \code{end}, \code{width}] the start, end, or width
of the window. If \code{by} is missing, then must supply two of the
three.
\item[\code{frequency}, \code{delta}] Optional arguments that specify
the sampling frequency and increment within the window.
\item[\dots] Further arguments for \code{FUN}.
\item[\code{simplify}] A logical value specifying whether or not the
result should be simplified to a vector or matrix if possible.
}

}
\end{Section}
\begin{Section}{Coercion}
In the code snippets below, \code{x} is a Sequence object.

\describe{
\item[] \code{as.env(x, enclos = parent.frame())}:
Creates an environment from \code{x} with a symbol for each
\code{names(x)}. The values are not actually copied into the
environment. Rather, they are dynamically bound using
\code{\LinkA{makeActiveBinding}{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.

\item[] \code{as.list(x, ...)}, \code{as(from, "list")}:
Turns \code{x} into a standard list.

\item[] \code{stack(x, indName = "space", valuesName = "values")}:
As with \code{\LinkA{stack}{stack}} on a \code{list},
constructs a \code{DataFrame} with two columns: one for the
unlisted values, the other indicating the name of the element from
which each value was obtained. \code{indName} specifies the column
name for the index (source name) column and \code{valuesName}
specifies the column name for the values.

}
\end{Section}
\begin{Section}{Functional Programming}
The R base package defines some Higher-Order functions that are commonly
found in Functional Programming Languages. See \code{?\LinkA{Reduce}{Reduce}}
for the details, and, in particular, for a description of their arguments.
The IRanges package provides methods for Sequence objects, so, in addition
to be a vector, the \code{x} argument can also be a Sequence object.

\describe{
\item[] \code{Reduce(f, x, init, right = FALSE, accumulate = FALSE)}:
Uses a binary function to successively combine the elements of \code{x}
and a possibly given initial value.
See \code{?\LinkA{Reduce}{Reduce}} (in the base package) for the details.

\item[] \code{Filter(f, x)}:
Extracts the elements of \code{x} for which function \code{f} is TRUE.
See \code{?\LinkA{Filter}{Filter}} (in the base package) for the details.

\item[] \code{Find(f, x, right = FALSE, nomatch = NULL)}:
Extracts the first or last such element in \code{x}.
See \code{?\LinkA{Find}{Find}} (in the base package) for the details.

\item[] \code{Map(f, ...)}:
Applies a function to the corresponding elements of given Sequence
objects.
See \code{?\LinkA{Map}{Map}} (in the base package) for the details.

\item[] \code{Position(f, x, right = FALSE, nomatch = NA\_integer\_)}:
Extracts the first or last such position in \code{x}.
See \code{?\LinkA{Position}{Position}} (in the base package) for the details.

}
\end{Section}
\begin{Section}{Evaluating}
In the code snippets below, \code{envir} and \code{data} are Sequence
objects.

\describe{
\item[] \code{eval(expr, envir, enclos = parent.frame())}:
Converts the Sequence object specified in \code{envir} to an
environment using \code{as.env}, with \code{enclos} as its parent,
and then evaluates \code{expr} within that environment.

\item[] \code{with(data, expr, ...)}:
Equivalent to \code{eval(quote(expr), data, ...)}.

}
\end{Section}
\begin{Author}\relax
P. Aboyoun
\end{Author}
\begin{SeeAlso}\relax
\LinkA{Annotated}{Annotated.Rdash.class},
\LinkA{DataTable}{DataTable.Rdash.class},
\LinkA{SimpleList}{SimpleList.Rdash.class},
\LinkA{Ranges}{Ranges.Rdash.class},
\LinkA{Rle}{Rle.Rdash.class},
\LinkA{XVector}{XVector.Rdash.class} for example implementations
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  showClass("Sequence")  # shows (some of) the known subclasses
\end{ExampleCode}
\end{Examples}

