GTuplesList-class {GenomicTuples} | R Documentation

## GTuplesList objects

### Description

The `GTuplesList` class is a container for storing a collection of `GTuples` objects. It is derived from `GRangesList`.

### Constructor

  `GTuplesList(...)`: Creates a `GTuplesList` object using `GTuples` objects supplied in `...`.

### Accessors

In the following code snippets, `x` is a `GTuplesList` object.

  `length(x)`: Get the number of list elements.

  `names(x)`, `names(x) <- value`: Get or set the names on `x`.

  `elementNROWS(x)`: Get the `length` of each of the list elements.

  `isEmpty(x)`: Returns a logical indicating either if the `GTuplesList` has no elements or if all its elements are empty.

  `seqnames(x)`, `seqnames(x) <- value`: Get or set the sequence names in the form of an `RleList`. `value` can be an `RleList` or `CharacterList` object.

  `tuples(x)`, `tuples(x) <- value`: Get or set the tuples in the form of a `SimpleList` of integer matrices. `value` can be a a single integer matrix.

  `ranges(x, use.mcols = FALSE)`, `ranges(x) <- value`: Get or set the ranges in the form of a `CompressedIRangesList`. `value` can be a `IntegerRangesList` object.

  WARNING: The use of `ranges` with `GTuplesList` objects is strongly discouraged. It will only get/set pos_{1} and pos_{m} of the tuples, where m is the `size` of the tuples, as these are what are stored in the "ranges" slot of the `GTuples` objects.

  `strand(x)`, `strand(x) <- value`: Get or set the strand in the form of an `RleList`. `value` can be an `RleList`, `CharacterList` or single character. `value` as a single character converts all ranges in `x` to the same `value`; for selective strand conversion (i.e., mixed “+” and “-”) use `RleList` or `CharacterList`.

  `mcols(x, use.names=FALSE)`, `mcols(x) <- value`: Get or set the metadata columns. `value` can be `NULL`, or a data.frame-like object (i.e. `DataFrame` or data.frame) holding element-wise metadata.

  `elementMetadata(x)`, `elementMetadata(x) <- value`, `values(x)`, `values(x) <- value`: Alternatives to `mcols` functions. Their use is discouraged.

  `seqinfo(x)`, `seqinfo(x) <- value`: Get or set the information about the underlying sequences. `value` must be a Seqinfo object.

  `seqlevels(x)`, `seqlevels(x, force=FALSE) <- value`: Get or set the sequence levels. `seqlevels(x)` is equivalent to `seqlevels(seqinfo(x))` or to `levels(seqnames(x))`, those 2 expressions being guaranteed to return identical character vectors on a `GTuplesList` object. `value` must be a character vector with no NAs. See `?seqlevels` for more information.

  `seqlengths(x)`, `seqlengths(x) <- value`: Get or set the sequence lengths. `seqlengths(x)` is equivalent to `seqlengths(seqinfo(x))`. `value` can be a named non-negative integer or numeric vector eventually with NAs.

  `isCircular(x)`, `isCircular(x) <- value`: Get or set the circularity flags. `isCircular(x)` is equivalent to `isCircular(seqinfo(x))`. `value` must be a named logical vector eventually with NAs.

  `genome(x)`, `genome(x) <- value`: Get or set the genome identifier or assembly name for each sequence. `genome(x)` is equivalent to `genome(seqinfo(x))`. `value` must be a named character vector eventually with NAs.

  `seqlevelsStyle(x)`, `seqlevelsStyle(x) <- value`: Get or set the seqname style for `x`. See the seqlevelsStyle generic getter and setter in the GenomeInfoDb package for more information.

  `score(x), score(x) <- value`: Get or set the “score” metadata column.

### Tuples methods

In the following code snippets, x is a `GTuplesList` object.

WARNING: The preferred setter is `tuples(x) <- value` and the use of `start(x) <- value`, `end(x) <- value` and `width(x) <- value is discouraged`.

  `start(x)`, `start(x) <- value`: Get or set pos_{1} of the `tuples`. WARNING: The use of `start(x) <- value` is discouraged; instead, construct the tuples as the appropriate `List` of integer matrices, `mvalue`, and use `tuples(x) <- mvalue`.

  `end(x)`, `end(x) <- value`: Get or set pos_{m} of the tuples, where m is the `size` of the tuples. WARNING: The use of `end(x) <- value` is discouraged; instead, construct the tuples as the appropriate `List` of integer matrices, `mvalue`, and use `tuples(x) <- mvalue`.

  `IPD(x)`: Get the intra-pair distances (`IPD`) in the form of a `SimpleList` of integer matrices. `IPD` is only defined for tuples with `size` > 1. The `IPD` of a tuple with `size`= m is the vector of intra-pair distances, (pos_{2} - pos_{1}, …, pos_{m} - pos_{m - 1}).

  `width(x)`, `width(x) <- value`: Get or set pos_{m} - pos_{1} of the tuples, where m is the `size` of the tuples. If using `width(x) <- value`, pos_{1} is held fixed and pos_{m} is altered. WARNING: The use of `width(x) <- value` is discouraged; instead, instead, construct the tuples as the appropriate `List` of integer matrices, `mvalue`, and use `tuples(x) <- mvalue`.

### Coercion

In the code snippets below, `x` is a GTuplesList object.

  `as.data.frame(x, row.names = NULL, optional = FALSE, ..., value.name = "value", use.outer.mcols = FALSE, group_name.as.factor = FALSE)`: Coerces `x` to a `data.frame`. See as.data.frame on the `List` man page for details (?`List`).

  `as.list(x, use.names = TRUE)`: Creates a list containing the elements of `x`.

  `as(x, "GRangesList")`: Creates a `GRangesList` object from a `GTuplesList` object. WARNING: This is generally a destructive operation, as the original `GTuplesList` may not be re-creatable.

### Subsetting

In the following code snippets, `x` is a `GTuplesList` object.

  `x[i, j]`, `x[i, j] <- value`: Get or set elements `i` with optional metadata columns `mcols(x)[,j]`, where `i` can be missing; an NA-free logical, numeric, or character vector; a 'logical' Rle object, or an AtomicList object.

  `x[[i]]`, `x[[i]] <- value`: Get or set element `i`, where `i` is a numeric or character vector of length 1.

  `x$name`, `x$name <- value`: Get or set element `name`, where `name` is a name or character vector of length 1.

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

  `rep(x, times, length.out, each)`: 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.

  `subset(x, subset)`: Returns a new object of the same class as `x` made of the subset using logical vector `subset`, where missing values are taken as `FALSE`.

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

### Combining

In the code snippets below, `x` is a GTuplesList object.

  `c(x, ...)`: Combines `x` and the GTuplesList objects in `...` together. Any object in `...` must belong to the same class as `x`, or to one of its subclasses, or must be `NULL`. The result is an object of the same class as `x`.

  `append(x, values, after = length(x))`: Inserts the `values` into `x` at the position given by `after`, where `x` and `values` are of the same class.

  `unlist(x, recursive = TRUE, use.names = TRUE)`: Concatenates the elements of `x` into a single GTuples object.

### Looping

In the code snippets below, `x` is a GTuplesList object.

  `endoapply(X, FUN, ...)`: Similar to `lapply`, but performs an endomorphism, i.e. returns an object of `class(X)`.

  `lapply(X, FUN, ...)`: Like the standard `lapply` function defined in the base package, the `lapply` method for GTuplesList objects returns a list of the same length as `X`, with each element being the result of applying `FUN` to the corresponding element of `X`.

  `Map(f, ...)`: Applies a function to the corresponding elements of given GTuplesList objects.

  `mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)`: Like the standard `mapply` function defined in the base package, the `mapply` method for GTuplesList objects is a multivariate version of `sapply`.

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

  `Reduce(f, x, init, right = FALSE, accumulate = FALSE)`: Uses a binary function to successively combine the elements of `x` and a possibly given initial value.

  f

    A binary argument function.

  init

    An R object of the same kind as the elements of `x`.

  right

    A logical indicating whether to proceed from left to right (default) or from right to left.

  nomatch

    The value to be returned in the case when "no match" (no element satisfying the predicate) is found.

  `sapply(X, FUN, ..., simplify=TRUE, USE.NAMES=TRUE)`: Like the standard `sapply` function defined in the base package, the `sapply` method for GTuplesList objects is a user-friendly version of `lapply` by default returning a vector or matrix if appropriate.

### Author(s)

Peter Hickey for `GTuplesList` definition and methods. P. Aboyoun & H. Pagès for all the real work underlying the powerful `GRangesList` class and methods.

### See Also

GTuples-class `seqinfo`, GRangesList-class, Vector-class, IntegerRangesList-class, RleList-class, DataFrameList-class, findOverlaps-methods

### Examples

      ## Construction of GTuplesList of 4-tuples with GTuplesList():
      seqinfo <- Seqinfo(paste0("chr", 1:3), c(1000, 2000, 1500), NA, "mock1")
      gt4 <- GTuples(seqnames = Rle(c("chr1", "chr2", "chr1", "chr3"),
                                    c(1, 3, 2, 4)),
                     tuples = matrix(c(1:10, 2:11, 3:12, 4:13), ncol = 4),
                     strand = Rle(strand(c("-", "+", "*", "+", "-")),
                                  c(1, 2, 2, 3, 2)),
                     score = 1:10, GC = seq(1, 0, length = 10), seqinfo = seqinfo)
      gtl4 <- GTuplesList(A = gt4[1:4], B = gt4[5:10])
      gtl4

      ## Summarizing elements:
      elementNROWS(gtl4)
      table(seqnames(gtl4))

      ## Extracting subsets:
      gtl4[seqnames(gtl4) == "chr1", ]
      gtl4[seqnames(gtl4) == "chr1" & strand(gtl4) == "+", ]

      ## Renaming the underlying sequences:
      seqlevels(gtl4)
      seqlevels(gtl4) <- sub("chr", "Chrom", seqlevels(gtl4))
      gtl4

      ## Coerce to GRangesList ("internal positions" information is lost):
      as(gtl4, "GRangesList")

      ## Get the size of the tuples stored in the GTuplesList object
      size(gtl4)

      ## Get the tuples
      tuples(gtl4)

      ## Get the matrix of intra-pair distances (IPD)
      IPD(gtl4)

      ## Can't combine genomic tuples of different sizes
      gt1 <- GTuples('chr1', matrix(30:40))
      gt1
      ## Not run:
      ## Returns error
      GTuplesList(A = gt4, gt1)

    ## End(Not run)

[Package GenomicTuples version 1.20.0 Index]