\HeaderA{Ranges-utils}{Ranges utility functions}{Ranges.Rdash.utils}
\aliasA{flank}{Ranges-utils}{flank}
\aliasA{flank,NormalIRanges-method}{Ranges-utils}{flank,NormalIRanges.Rdash.method}
\aliasA{flank,Ranges-method}{Ranges-utils}{flank,Ranges.Rdash.method}
\aliasA{narrow}{Ranges-utils}{narrow}
\aliasA{narrow,NormalIRanges-method}{Ranges-utils}{narrow,NormalIRanges.Rdash.method}
\aliasA{narrow,Ranges-method}{Ranges-utils}{narrow,Ranges.Rdash.method}
\aliasA{range,IRanges-method}{Ranges-utils}{range,IRanges.Rdash.method}
\aliasA{range,Ranges-method}{Ranges-utils}{range,Ranges.Rdash.method}
\aliasA{reduce}{Ranges-utils}{reduce}
\aliasA{reduce,IRanges-method}{Ranges-utils}{reduce,IRanges.Rdash.method}
\aliasA{reduce,Ranges-method}{Ranges-utils}{reduce,Ranges.Rdash.method}
\aliasA{reflect}{Ranges-utils}{reflect}
\aliasA{reflect,NormalIRanges-method}{Ranges-utils}{reflect,NormalIRanges.Rdash.method}
\aliasA{reflect,Ranges-method}{Ranges-utils}{reflect,Ranges.Rdash.method}
\aliasA{resize}{Ranges-utils}{resize}
\aliasA{resize,NormalIRanges-method}{Ranges-utils}{resize,NormalIRanges.Rdash.method}
\aliasA{resize,Ranges-method}{Ranges-utils}{resize,Ranges.Rdash.method}
\aliasA{restrict}{Ranges-utils}{restrict}
\aliasA{restrict,NormalIRanges-method}{Ranges-utils}{restrict,NormalIRanges.Rdash.method}
\aliasA{restrict,Ranges-method}{Ranges-utils}{restrict,Ranges.Rdash.method}
\aliasA{shift}{Ranges-utils}{shift}
\aliasA{shift,Ranges-method}{Ranges-utils}{shift,Ranges.Rdash.method}
\aliasA{threebands}{Ranges-utils}{threebands}
\aliasA{threebands,IRanges-method}{Ranges-utils}{threebands,IRanges.Rdash.method}
\keyword{utilities}{Ranges-utils}
\begin{Description}\relax
Utility functions for modifying \LinkA{Ranges}{Ranges} objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
reflect(x, bounds, use.names=TRUE)
resize(x, width, fix="start", use.names=TRUE, ...)
restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
shift(x, shift, use.names=TRUE)

## S4 method for signature 'Ranges':
range(x, ..., na.rm = FALSE)
## S4 method for signature 'Ranges':
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
       with.inframe.attrib=FALSE)

threebands(x, start=NA, end=NA, width=NA)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An \LinkA{Ranges}{Ranges} object.

\item[\code{width}] For \code{narrow} and \code{threebands}, a vector of integers, eventually
with NAs. See the SEW (Start/End/Width) interface for the details
(\code{?solveUserSEW}).

For \code{resize} and \code{flank}, the width of the resized or flanking
regions. Note that if \code{both} is \code{TRUE}, this is effectively
doubled. Recycled as necessary so that each element corresponds to a range
in \code{x}.

\item[\code{start, end}] A single integer or \code{NA} for all functions except \code{narrow},
\code{threebands}, and \code{flank}.

For \code{narrow} and \code{threebands}, the supplied \code{start}
and \code{end} arguments must be vectors of integers, eventually with NAs,
that contain coordinates relative to the current ranges.
See the Details section below.

For \code{flank}, \code{start} is a logical indicating whether \code{x}
should be flanked at the start (\code{TRUE}) or the end (\code{FALSE}).
Recycled as necessary so that each element corresponds to a range in
\code{x}.

\item[\code{both}] If \code{TRUE}, extends the flanking region \code{width} positions
\emph{into} the range. The resulting range thus straddles the end
point, with \code{width} positions on either side.

\item[\code{use.names}] \code{TRUE} or \code{FALSE}. Should names be preserved?

\item[\code{bounds}] An \LinkA{IRanges}{IRanges} object to serve as the reference bounds for the
reflection, see below.

\item[\code{fix}] For \code{resize}, a character vector or character Rle of length 1 or
\code{length(x)} containing the values \code{"start"}, \code{"end"},
and \code{"center"} denoting what to use as an anchor for each element
in \code{x}.

\item[\code{keep.all.ranges}] \code{TRUE} or \code{FALSE}. Should ranges that don't overlap with
the interval specified by \code{start} and \code{end} be kept?
Note that "don't overlap" means that they end strictly before
\code{start - 1} or start strictly after \code{end + 1}.
Ranges that end at \code{start - 1} or start at \code{end + 1}
are always kept and their width is set to zero in the returned
\LinkA{IRanges}{IRanges} object.

\item[\code{shift}] A single integer.

\item[\code{drop.empty.ranges}] \code{TRUE} or \code{FALSE}. Should empty ranges be dropped?

\item[\code{min.gapwidth}] Ranges separated by a gap of at least \code{min.gapwidth} positions
won't be merged in the \LinkA{Ranges}{Ranges} object returned by \code{reduce}.
Otherwise, they will.

\item[\code{with.inframe.attrib}] \code{TRUE} or \code{FALSE}. For internal use.

\item[\code{...}] For \code{range}, additional \code{Ranges} to consider.

\item[\code{na.rm}] Ignored
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{flank} generates flanking ranges for each range in \code{x}. If
\code{start} is \code{TRUE} for a given range, the flanking occurs at
the start, otherwise the end. The widths of the flanks are given by
the \code{width} parameter. The widths can be negative, in which case
the flanking region is reversed so that it represents a prefix or
suffix of the range in \code{x}. The \code{flank} operation is
illustrated below for a call of the form \code{flank(x, 3, TRUE)},
where \code{x} indicates a range in \code{x} and \code{-} indicates
the resulting flanking region:
\begin{alltt}
    ---xxxxxxx
\end{alltt}
If \code{start} were \code{FALSE}:
\begin{alltt}
       xxxxxxx---
\end{alltt}
For negative width, i.e. \code{flank(x, -3, FALSE)}, where \code{*}
indicates the overlap between \code{x} and the result:
\begin{alltt}
       xxxx***
\end{alltt}
If \code{both} is \code{TRUE}, then, for
all ranges in \code{x}, the flanking regions are extended \emph{into}
(or out of, if width is negative)
the range, so that the result straddles the given endpoint and has
twice the width given by \code{width}. This is illustrated below for
\code{flank(x, 3, both=TRUE)}:
\begin{alltt}
    ---***xxxx
\end{alltt}

\code{narrow} narrows the ranges in \code{x} i.e. each range in the
returned \LinkA{Ranges}{Ranges} object is a subrange of the corresponding
range in \code{x}.
The supplied start/end/width values are solved by a call to
\code{solveUserSEW(width(x), start=start, end=end, width=width)}
and therefore must be compliant with the rules of the SEW
(Start/End/Width) interface (see \code{?\LinkA{solveUserSEW}{solveUserSEW}}
for the details).
Then each subrange is derived from the original range according
to the solved start/end/width values for this range. Note that those
solved values are interpreted relatively to the original range.

\code{reflect} "reflects" or reverses each range in \code{x} relative to
the corresponding range in \code{bounds}, which is recycled as
necessary. Reflection preserves the width of a range, but shifts it
such the distance from the left bound to the start of the range
becomes the distance from the end of the range to the right
bound. This is illustrated below, where \code{x} represents
a range in \code{x} and \code{[} and \code{]} indicate the bounds:
\begin{alltt}
    [..xxx.....]
    becomes
    [.....xxx..]
\end{alltt}

\code{resize} resizes the ranges to the specified width where either the
start, end, or center is used as an anchor.

\code{restrict} restricts the ranges in \code{x} to the interval
specified by the \code{start} and \code{end} arguments.

\code{shift} shifts all the ranges in \code{x}.

\code{range} returns an \code{IRanges} instance with a single range,
from the minimum start to the maximum end in the combined ranges of
\code{x} and the arguments in \code{...}.

\code{reduce} first orders the ranges in \code{x} from left to right,
then merges the overlapping or adjacent ones.

\code{threebands} extends the capability of \code{narrow} by returning
the 3 ranges objects associated to the narrowing operation.
The returned value \code{y} is a list of 3 ranges objects named
\code{"left"}, \code{"middle"} and \code{"right"}.
The middle component is obtained by calling \code{narrow} with the
same arguments (except that names are dropped). The left and right
components are also instances of the same class as \code{x} and they
contain what has been removed on the left and right sides (respectively)
of the original ranges during the narrowing.

Note that original object \code{x} can be reconstructed from the
left and right bands with \code{punion(y\$left, y\$right, fill.gap=TRUE)}.
\end{Details}
\begin{Author}\relax
H. Pages, M. Lawrence, P. Aboyoun
\end{Author}
\begin{SeeAlso}\relax
\code{threebands} could be described as a parallel variant
of \code{\LinkA{disjoin}{disjoin}}.

\LinkA{Ranges-class}{Ranges.Rdash.class},
\LinkA{IRanges-setops}{IRanges.Rdash.setops},
\code{\LinkA{solveUserSEW}{solveUserSEW}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  vec <- as.integer(c(19, 5, 0, 8, 5))
  x <- successiveIRanges(vec)
  x

  shift(x, -3)

  restrict(x, start=12, end=34)
  restrict(x, start=20)
  restrict(x, start=21)
  restrict(x, start=21, keep.all.ranges=TRUE)

  y <- x[width(x) != 0]
  narrow(y, start=4, end=-2)
  narrow(y, start=-4, end=-2)
  narrow(y, end=5, width=3)
  narrow(y, start = c(3, 4, 2, 3), end = c(12, 5, 7, 4))

  resize(y, width = 200)
  resize(y, width = 2, fix = "end")

  z <- threebands(y, start=4, end=-2)
  y0 <- punion(z$left, z$right, fill.gap=TRUE)
  identical(y, y0)  # TRUE
  threebands(y, start=-5)

  x <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 3, 10),
               width=c( 5, 0, 6,  1, 4, 3,  2, 0,  3))
  reduce(x)
  reduce(x, drop.empty.ranges=TRUE)

  ir1 <- IRanges(c(2,5,1), c(3,7,3))

  bounds <- IRanges(c(0, 5, 3), c(10, 6, 9))
  reflect(ir1, bounds)

  flank(ir1, 2)
  flank(ir1, 2, FALSE)
  flank(ir1, 2, c(FALSE, TRUE, FALSE))
  flank(ir1, c(2, -2, 2))
  flank(ir1, 2, both = TRUE)
  flank(ir1, 2, FALSE, TRUE)
  flank(ir1, -2, FALSE, TRUE)
\end{ExampleCode}
\end{Examples}

