Rle-class              package:IRanges              R Documentation

Rle objects

Description:

     The Rle class is a general container for storing an atomic vector
     that is stored in a run-length encoding format. It is based on the
     'rle' function from the base package.

Constructors:


      'Rle(values)': This constructor creates an Rle instances out of
          an atomic vector 'values'.

      'Rle(values, lengths)': This constructor creates an Rle instances
          out of an atomic vector or factor object 'values' and an
          integer or numeric vector 'lengths' with all positive
          elements that represent how many times each value is
          repeated. The length of these two vectors must be the same.

      'as(from, "Rle")': This constructor creates an Rle instances out
          of an atomic vector 'from'.


Accessors:

     In the code snippets below, 'x' is an Rle object:


      'runLength(x)': Returns the run lengths for 'x'.

      'runValue(x)': Returns the run values for 'x'.

      'nrun(x)': Returns the number of runs in 'x'.

      'start(x)': Returns the starts of the runs for 'x'.

      'end(x)': Returns the ends of the runs for 'x'.

      'width(x)': Same as 'runLength(x)'.


Replacers:

     In the code snippets below, 'x' is an Rle object:


      'runLength(x) <- value': Replaces 'x' with a new Rle object using
          run values 'runValue(x)' and run lengths 'value'.

      'runValue(x) <- value': Replaces 'x' with a new Rle object using
          run values 'value' and run lengths 'runLength(x)'.


Coercion:

     In the code snippets below, 'x' and 'from' are Rle objects:


      'as.vector(x)', 'as(from, "vector")': Creates an atomic vector of
          the most appropriate type based on the values contained in
          'x'.

      'as.logical(x)', 'as(from, "logical")': Creates a logical vector
          based on the values contained in 'x'.

      'as.integer(x)', 'as(from, "integer")': Creates an integer vector
          based on the values contained in 'x'.

      'as.numeric(x)', 'as(from, "numeric")': Creates a numeric vector
          based on the values contained in 'x'.

      'as.complex(x)', 'as(from, "complex")': Creates a complex vector
          based on the values contained in 'x'.

      'as.character(x)', 'as(from, "character")': Creates a character
          vector based on the values contained in 'x'.

      'as.raw(x)', 'as(from, "raw")': Creates a raw vector based on the
          values contained in 'x'.

      'as.factor(x)', 'as(from, "factor")': Creates a factor object
          based on the values contained in 'x'.

      'as.data.frame(x)', 'as(from, "data.frame")': Creates a
          'data.frame' with a single column holding the result of
          'as.vector(x)'.

      'as(from, "IRanges")': Creates an IRanges instance from a logical
          Rle. Note that this instance is guaranteed to be normal.

      'as(from, "NormalIRanges")': Creates a NormalIRanges instance
          from a logical Rle.


Group Generics:

     Rle objects have support for S4 group generic functionality:

     'Arith' '"+"', '"-"', '"*"', '"^"', '"%%"', '"%/%"', '"/"'

     'Compare' '"=="', '">"', '"<"', '"!="',  '"<="', '">="'

     'Logic' '"&"', '"|"'

     'Ops' '"Arith"', '"Compare"', '"Logic"'

     'Math' '"abs"', '"sign"', '"sqrt"', '"ceiling"', '"floor"',
          '"trunc"', '"cummax"', '"cummin"', '"cumprod"', '"cumsum"',
          '"log"', '"log10"', '"log2"', '"log1p"', '"acos"', '"acosh"',
          '"asin"', '"asinh"', '"atan"', '"atanh"', '"exp"', '"expm1"',
          '"cos"', '"cosh"', '"sin"', '"sinh"', '"tan"', '"tanh"',
          '"gamma"', '"lgamma"', '"digamma"', '"trigamma"'

     'Math2' '"round"', '"signif"'

     'Summary' '"max"', '"min"', '"range"', '"prod"', '"sum"', '"any"',
          '"all"'

     'Complex' '"Arg"', '"Conj"', '"Im"', '"Mod"', '"Re"'

     See S4groupGeneric for more details.

General Methods:

     In the code snippets below, 'x' is an Rle object:


      'x[i, drop = !is.null(getOption("dropRle")) &&
          getOption("dropRle")]': Subsets 'x' by index 'i', where 'i'
          can be positive integers, negative integers, a logical vector
          of the same length as 'x', an Rle object of the same length
          as 'x' containing logical values, or an IRanges object. When
          'drop = FALSE' returns an Rle object. When 'drop = TRUE',
          returns an atomic vector.

      'x[i] <- value': Equivalent to 'seqselect(x, i) <- value'.

      'x %in% table': Returns a logical Rle representing set membership
          in 'table'.

      '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:

          'by' An object with 'start', 'end', and 'width' methods.

          'FUN' The function, found via 'match.fun', to be applied to
               each window of 'x'.

          'start', 'end', 'width' the start, end, or width of the
               window. If 'by' is missing, then must supply two of the
               three.

          'frequency', 'delta' Optional arguments that specify the
               sampling frequency and increment within the window.

          ... Further arguments for 'FUN'.

          'simplify' A logical value specifying whether or not the
               result should be simplified to a vector or matrix if
               possible.


      'append(x, values, after = length(x))': Insert one Rle into
          another Rle.

          'values' the Rle to insert.

          'after' the subscript in 'x' after which the values are to be
               inserted.


      'c(x, ...)': Combines a set of Rle objects.

      'findRange(x, vec)': Returns an IRanges object representing the
          ranges in Rle 'vec' that are referenced by the indices in the
          integer vector 'x'.

      'findRun(x, vec)': Returns an integer vector indicating the run
          indices in Rle 'vec' that are referenced by the indices in
          the integer vector 'x'.

      'head(x, n = 6L)': If 'n' is non-negative, returns the first n
          elements of 'x'. If 'n' is negative, returns all but the last
          'abs(n)' elements of 'x'.

      'is.na(x)': Returns a logical Rle indicating with values are
          'NA'.

      'is.unsorted(x, na.rm = FALSE, strictly = FALSE)': Returns a
          logical value specifying if 'x' is unsorted.

          'na.rm' remove missing values from check.

          'strictly' check for _strictly_ increasing values.


      'length(x)': Returns the underlying vector length of 'x'.

      'match(x, table, nomatch = NA_integer_, incomparables = NULL)':
          Matches the values in 'x' to 'table':

          'table' the values to be matched against.

          'nomatch' the value to be returned in the case when no match
               is found.

          'incomparables' a vector of values that cannot be matched.
               Any value in 'x' matching a value in this vector is
               assigned the 'nomatch' value.


      'rep(x, times, length.out, each)', 'rep.int(x, times)': Repeats
          the values in 'x' through one of the following conventions:

          'times' Vector giving the number of times to repeat each
               element if of length 'length(x)', or to repeat the whole
               vector if of length 1.

          'length.out' Non-negative integer. The desired length of the
               output vector.

          'each' Non-negative integer.  Each element of 'x' is repeated
               'each' times.


      'rev(x)': Reverses the order of the values in 'x'.

      'seqselect(x, start = NULL, end = NULL, width = NULL)': Creates a
          new Rle object using consecutive subsequences from 'x'
          specified by two of the three following values:  'start',
          'end', and 'width'. See seqselect for more details.

      'seqselect(x, start=NULL, end=NULL, width=NULL) <- value':
          Similar to 'window<-', except that multiple consecutive
          subsequences can be replaced by a constant 'value'. As such
          two of the three 'start', 'end', and 'width' arguments can be
          used to specify the consecutive subsequences. Alternatively,
          '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.

      'shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE,
          verbose = FALSE)': Let 'i' be the indices in 'SHIFT', 'X_i =
          window(X, 1 + OFFSET, length(X) - SHIFT[i])', and 'Y_i =
          window(Y, 1 + SHIFT[i], length(Y) - OFFSET)'. Calculates the
          set of 'FUN(X_i, Y_i, ...)' values and return the results in
          a convenient form:

          'SHIFT' A non-negative integer vector of shift values.

          'X', 'Y' The Rle objects to shift.

          'FUN' The function, found via 'match.fun', to be applied to
               each set of shifted vectors.

          ... Further arguments for 'FUN'.

          OFFSET A non-negative integer offset to maintain throughout
               the shift operations.

          'simplify' A logical value specifying whether or not the
               result should be simplified to a vector or matrix if
               possible.

          'verbose' A logical value specifying whether or not to print
               the 'i' indices to track the iterations.


      'show(object)': Prints out the Rle object in a user-friendly way.

      'sort(x, decreasing = FALSE, na.last = NA)': Sorts the values in
          'x'.

          'decreasing' If 'TRUE', sort values in decreasing order. If
               'FALSE', sort values in increasing order.

          'na.last' If 'TRUE', missing values are placed last. If
               'FALSE', they are placed first. If 'NA', they are
               removed.


      'split(x, f, drop = FALSE)': Splits 'x' according to 'f' to
          create a CompressedRleList object. Empty list elements are
          removed if 'drop' is 'TRUE'.

      'splitRanges(x)': Returns a CompressedIRangesList object that
          contain the ranges for each of the unique run values. 

      'subset(x, subset)': Returns a new Rle object made of the subset
          using logical vector 'subset'.

      'summary(object, ..., digits = max(3, getOption("digits") - 3))':
          Summarizes the Rle object using an atomic vector convention.
          The 'digits' argument is used for number formatting with
          'signif()'.

      'table(...)': Returns a table containing the counts of the unique
          values.

      'tail(x, n = 6L)': If 'n' is non-negative, returns the last n
          elements of 'x'. If 'n' is negative, returns all but the
          first 'abs(n)' elements of 'x'.

      'unique(x, incomparables = FALSE, ...)': Returns the unique run
          values. The 'incomparables' argument takes a vector of values
          that cannot be compared with 'FALSE' being a special value
          that means that all values can be compared. 

      'window(x, start = NA, end = NA, width = NA, frequency = NULL,
          delta = NULL, ...)': Extract the subsequence window from 'x'
          specified by:

          'start', 'end', 'width' The start, end, or width of the
               window. Two of the three are required.

          'frequency', 'delta' Optional arguments that specify the
               sampling frequency and increment within the window.


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


Logical Data Methods:

     In the code snippets below, 'x' is an Rle object:


      '!x': Returns logical negation (NOT) of 'x'.

      'which(x)': Returns an integer vector representing the 'TRUE'
          indices of 'x'.


Numerical Data Methods:

     In the code snippets below, 'x' is an Rle object:


      'diff(x, lag = 1, differences = 1': Returns suitably lagged and
          iterated differences of 'x'.

          'lag' An integer indicating which lag to use.

          'differences' An integer indicating the order of the
               difference.


      'pmax(..., na.rm = FALSE)', 'pmax.int(..., na.rm = FALSE)':
          Parallel maxima of the Rle input values. Removes 'NA's when
          'na.rm = TRUE'.

      'pmin(..., na.rm = FALSE)', 'pmin.int(..., na.rm = FALSE)':
          Parallel minima of the Rle input values. Removes 'NA's when
          'na.rm = TRUE'.

      'mean(x, na.rm = FALSE)': Calculates the mean of 'x'. Removes
          'NA's when 'na.rm = TRUE'.

      'var(x, y = NULL, na.rm = FALSE)': Calculates the variance of 'x'
          or covariance of 'x' and 'y' if both are supplied. Removes
          'NA's when 'na.rm = TRUE'.

      'cov(x, y, use = "everything")', 'cor(x, y, use = "everything")':
          Calculates the covariance and correlation respectively of Rle
          objects 'x' and 'y'. The 'use' argument is an optional
          character string giving a method for computing covariances in
          the presence of missing values. This must be (an abbreviation
          of) one of the strings '"everything"', '"all.obs"',
          '"complete.obs"', '"na.or.complete"', or
          '"pairwise.complete.obs"'.

      'sd(x, na.rm = FALSE)': Calculates the standard deviation of 'x'.
          Removes 'NA's when 'na.rm = TRUE'.

      'median(x, na.rm = FALSE)': Calculates the median of 'x'. Removes
          'NA's when 'na.rm = TRUE'.

      'quantile(x, probs = seq(0, 1, 0.25), na.rm = FALSE, names =
          TRUE, type = 7, ...)': Calculates the specified quantiles of
          'x'.

          'probs' A numeric vector of probabilities with values in
               [0,1].

          'na.rm' If 'TRUE', removes 'NA's from 'x' before the
               quantiles are computed.

          'names' If 'TRUE', the result has names describing the
               quantiles.

          'type' An integer between 1 and 9 selecting one of the nine
               quantile algorithms detailed in 'quantile'.

          ... Further arguments passed to or from other methods.


      'mad(x, center = median(x), constant = 1.4826, na.rm = FALSE, low
          = FALSE, high = FALSE)': Calculates the median absolute
          deviation of 'x'.

          'center' The center to calculate the deviation from.

          'constant' The scale factor.

          'na.rm' If 'TRUE', removes 'NA's from 'x' before the mad is
               computed.

          'low' If 'TRUE', compute the 'lo-median'.

          'high' If 'TRUE', compute the 'hi-median'.


      'IQR(x, na.rm = FALSE)': Calculates the interquartile range of
          'x'.

          'na.rm' If 'TRUE', removes 'NA's from 'x' before the IQR is
               computed.


      'smoothEnds(y, k = 3)': Smooth end points of an Rle 'y' using
          subsequently smaller medians and Tukey's end point rule at
          the very end.

          'k' An integer indicating the width of largest median window;
               must be odd.


      'runmean(x, k, endrule = c("drop", "constant"))': Calculates the
          means for fixed width running windows across 'x'.

          'k' An integer indicating the fixed width of the running
               window. Must be odd when 'endrule == "constant"'.

          endrule A character string indicating how the values at the
               beginning and the end (of the data) should be treated.

               '"drop"' do not extend the running statistics to be the
                    same length as the underlying vectors;

               '"constant"' copies running statistic to the first
                    values and analogously for the last ones making the
                    smoothed ends _constant_;



      'runmed(x, k, endrule = c("median", "keep", "drop",
          "constant"))': Calculates the medians for fixed width running
          windows across 'x'.

          'k' An integer indicating the fixed width of the running
               window. Must be odd when 'endrule != "drop"'.

          endrule A character string indicating how the values at the
               beginning and the end (of the data) should be treated.

               '"keep"' keeps the first and last k2 values at both
                    ends, where k2 is the half-bandwidth 'k2 = k %/%
                    2', i.e., 'y[j] = x[j]' for j in {1,...,k_2;
                    n-k_2+1,...,n} {j = 1,..,k2 and (n-k2+1),..,n};

               '"constant"' copies the running statistic to the first
                    values and analogously for the last ones making the
                    smoothed ends _constant_;

               '"median"' the default, smooths the ends by using
                    symmetrical medians of subsequently smaller
                    bandwidth, but for the very first and last value
                    where Tukey's robust end-point rule is applied, see
                    'smoothEnds'.



      'runsum(x, k, endrule = c("drop", "constant"))': Calculates the
          sums for fixed width running windows across 'x'.

          'k' An integer indicating the fixed width of the running
               window. Must be odd when 'endrule == "constant"'.

          endrule A character string indicating how the values at the
               beginning and the end (of the data) should be treated.

               '"drop"' do not extend the running statistics to be the
                    same length as the underlying vectors;

               '"constant"' copies running statistic to the first
                    values and analogously for the last ones making the
                    smoothed ends _constant_;



      'runwtsum(x, k, wt, endrule = c("drop", "constant"))': Calculates
          the sums for fixed width running windows across 'x'.

          'k' An integer indicating the fixed width of the running
               window. Must be odd when 'endrule == "constant"'.

          'wt' A numeric vector of length 'k' that provides the weights
               to use.

          endrule A character string indicating how the values at the
               beginning and the end (of the data) should be treated.

               '"drop"' do not extend the running statistics to be the
                    same length as the underlying vectors;

               '"constant"' copies running statistic to the first
                    values and analogously for the last ones making the
                    smoothed ends _constant_;



      'runq(x, k, i, endrule = c("drop", "constant"))': Calculates the
          order statistic for fixed width running windows across 'x'.

          'k' An integer indicating the fixed width of the running
               window. Must be odd when 'endrule == "constant"'.

          'i' An integer indicating which order statistic to calculate.

          endrule A character string indicating how the values at the
               beginning and the end (of the data) should be treated.

               '"drop"' do not extend the running statistics to be the
                    same length as the underlying vectors;

               '"constant"' copies running statistic to the first
                    values and analogously for the last ones making the
                    smoothed ends _constant_;



Character Data Methods:

     In the code snippets below, 'x' is an Rle object:


      'nchar(x, type = "chars", allowNA = FALSE)': Returns an integer
          Rle representing the number of characters in the
          corresponding values of 'x'.

          'type' One of 'c("bytes", "chars", "width")'.

          'allowNA' Should 'NA' be returned for invalid multibyte
               strings rather than throwing an error?


      'substr(x, start, stop)', 'substring(text, first, last =
          1000000L)': Returns a character or factor Rle containing the
          specified substrings beginning at 'start'/'first' and ending
          at 'stop'/'last'.

      'chartr(old, new, x)': Returns a character or factor Rle
          containing a translated version of 'x'.

          'old' A character string specifying the characters to be
               translated.

          'new' A character string specifying the translations.


      'tolower(x)': Returns a character or factor Rle containing a
          lower case version of 'x'.

      'toupper(x)': Returns a character or factor Rle containing an
          upper case version of 'x'.

      'sub(pattern, replacement, x, ignore.case = FALSE, perl = FALSE,
          fixed = FALSE, useBytes = FALSE)': Returns a character or
          factor Rle containing replacements based on matches
          determined by regular expression matching. See 'sub' for a
          description of the arguments.

      'gsub(pattern, replacement, x, ignore.case = FALSE, perl = FALSE,
          fixed = FALSE, useBytes = FALSE)': Returns a character or
          factor Rle containing replacements based on matches
          determined by regular expression matching. See 'gsub' for a
          description of the arguments.

      'paste(..., sep = " ", collapse = NULL)': Returns a character or
          factor Rle containing a concatenation of the values in '...'.


Factor Data Methods:

     In the code snippets below, 'x' is an Rle object:


      'levels(x)', 'levels(x) <- value': Gets and sets the factor
          levels, respectively.

      'nlevels(x)': Returns the number of factor levels.


Author(s):

     P. Aboyoun

See Also:

     'rle', Sequence-class, S4groupGeneric, IRanges-class

Examples:

       x <- Rle(10:1, 1:10)
       x

       runLength(x)
       runValue(x)
       nrun(x)

       diff(x)
       unique(x)
       sort(x)
       sqrt(x)
       x^2 + 2 * x + 1
       x[c(1,3,5,7,9)]
       window(x, 4, 14)
       range(x)
       table(x)
       sum(x)
       mean(x)
       x > 4
       aggregate(x, x > 4, mean)
       aggregate(x, FUN = mean, start = 1:(length(x) - 50), end = 51:length(x))

       y <- Rle(c(TRUE,TRUE,FALSE,FALSE,TRUE,FALSE,TRUE,TRUE,TRUE))
       y
       as.vector(y)
       rep(y, 10)
       c(y, x > 5)

       z <- c("the", "quick", "red", "fox", "jumps", "over", "the", "lazy", "brown", "dog")
       z <- Rle(z, seq_len(length(z)))
       chartr("a", "@", z)
       toupper(z)

