Rle-class              package:IRanges              R Documentation

_R_l_e _o_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_C_o_n_s_t_r_u_c_t_o_r_s:


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


_A_c_c_e_s_s_o_r_s:

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


_R_e_p_l_a_c_e_r_s:

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


_C_o_e_r_c_i_o_n:

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


_G_r_o_u_p _G_e_n_e_r_i_c_s:

     Rle objects have support for S4 group generic functionality:

     '_A_r_i_t_h' '"+"', '"-"', '"*"', '"^"', '"%%"', '"%/%"', '"/"'

     '_C_o_m_p_a_r_e' '"=="', '">"', '"<"', '"!="',  '"<="', '">="'

     '_L_o_g_i_c' '"&"', '"|"'

     '_O_p_s' '"Arith"', '"Compare"', '"Logic"'

     '_M_a_t_h' '"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"'

     '_M_a_t_h_2' '"round"', '"signif"'

     '_S_u_m_m_a_r_y' '"max"', '"min"', '"range"', '"prod"', '"sum"', '"any"',
          '"all"'

     '_C_o_m_p_l_e_x' '"Arg"', '"Conj"', '"Im"', '"Mod"', '"Re"'

     See S4groupGeneric for more details.

_G_e_n_e_r_a_l _M_e_t_h_o_d_s:

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

          '_b_y' An object with 'start', 'end', and 'width' methods.

          '_F_U_N' The function, found via 'match.fun', to be applied to
               each window of 'x'.

          '_s_t_a_r_t', '_e_n_d', '_w_i_d_t_h' the start, end, or width of the
               window. If 'by' is missing, then must supply two of the
               three.

          '_f_r_e_q_u_e_n_c_y', '_d_e_l_t_a' Optional arguments that specify the
               sampling frequency and increment within the window.

          ... Further arguments for 'FUN'.

          '_s_i_m_p_l_i_f_y' A logical value specifying whether or not the
               result should be simplified to a vector or matrix if
               possible.


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

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

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

          '_t_i_m_e_s' 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.

          '_l_e_n_g_t_h._o_u_t' Non-negative integer. The desired length of the
               output vector.

          '_e_a_c_h' Non-negative integer.  Each element of 'x' is repeated
               'each' times.


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

      'shiftApply(SHIFT, X, Y, FUN, ..., OFFSET = 0L, simplify = TRUE,
          verbose = FALSE))': Let 'i' be the indices in 'SHIFT', 'X_i =
          subseq(X, 1 + OFFSET, length(X) - SHIFT[i])', and 'Y_i =
          subseq(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:

          '_S_H_I_F_T' A non-negative integer vector of shift values.

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

          '_F_U_N' The function, found via 'match.fun', to be applied to
               each set of shifted vectors.

          ... Further arguments for 'FUN'.

          _O_F_F_S_E_T A non-negative integer offset to maintain throughout
               the shift operations.

          '_s_i_m_p_l_i_f_y' A logical value specifying whether or not the
               result should be simplified to a vector or matrix if
               possible.

          '_v_e_r_b_o_s_e' 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'.

          '_d_e_c_r_e_a_s_i_n_g' If 'TRUE', sort values in decreasing order. If
               'FALSE', sort values in increasing order.

          '_n_a._l_a_s_t' If 'TRUE', missing values are placed last. If
               'FALSE', they are placed first. If 'NA', they are
               removed.


      'subseq(x, start = NA, end = NA, width = NA)': Extract the
          subsequence from 'x' specified by two of the three following
          values:  'start', 'end', and 'width'. This is more efficient
          for extracting consecutive values than '['.

      '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 = NULL, end = NULL, width = NULL, frequency =
          NULL, delta = NULL, ...)': Extract the subsequence window
          from 'x' specified by:

          '_s_t_a_r_t', '_e_n_d', '_w_i_d_t_h' The start, end, or width of the
               window. Two of the three are required.

          '_f_r_e_q_u_e_n_c_y', '_d_e_l_t_a' Optional arguments that specify the
               sampling frequency and increment within the window.


_L_o_g_i_c_a_l _D_a_t_a _M_e_t_h_o_d_s:

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


_N_u_m_e_r_i_c_a_l _D_a_t_a _M_e_t_h_o_d_s:

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


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

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

          '_l_a_g' An integer indicating which lag to use.

          '_d_i_f_f_e_r_e_n_c_e_s' An integer indicating the order of the
               difference.


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

          '_p_r_o_b_s' A numeric vector of probabilities with values in
               [0,1].

          '_n_a._r_m' If 'TRUE', removes 'NA's from 'x' before the
               quantiles are computed.

          '_n_a_m_e_s' If 'TRUE', the result has names describing the
               quantiles.

          '_t_y_p_e' 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'.

          '_c_e_n_t_e_r' The center to calculate the deviation from.

          '_c_o_n_s_t_a_n_t' The scale factor.

          '_n_a._r_m' If 'TRUE', removes 'NA's from 'x' before the mad is
               computed.

          '_l_o_w' If 'TRUE', compute the 'lo-median'.

          '_h_i_g_h' If 'TRUE', compute the 'hi-median'.


_C_h_a_r_a_c_t_e_r _D_a_t_a _M_e_t_h_o_d_s:

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

          '_t_y_p_e' One of 'c("bytes", "chars", "width")'.

          '_a_l_l_o_w_N_A' 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 Rle containing the specified
          substrings beginning at 'start'/'first' and ending at
          'stop'/'last'.

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

          '_o_l_d' A character string specifying the characters to be
               translated.

          '_n_e_w' A character string specifying the translations.


      'tolower(x)': Returns a lower case version of 'x'.

      'toupper(x)': Returns an upper case version of 'x'.

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

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


_A_u_t_h_o_r(_s):

     P. Aboyoun

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

       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)]
       subseq(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)

