GRangesList-class {GenomicRanges} | R Documentation

## GRangesList objects

### Description

The GRangesList class is a container for storing a collection of GRanges objects. It is derived from GenomicRangesList.

### Constructors

  `GRangesList(...)`: Creates a GRangesList object using GRanges objects supplied in `...`, either consecutively or in a list.

  `makeGRangesListFromFeatureFragments(seqnames=Rle(factor()), fragmentStarts=list(), fragmentEnds=list(), fragmentWidths=list(), strand=character(0), sep=",")`: Constructs a GRangesList object from a list of fragmented features. See the Examples section below.

### Accessors

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

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

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

  `elementNROWS(x)`: Get a vector of the `length` of each of the list element.

  `isEmpty(x)`: Returns a logical indicating either if the GRangesList 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.

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

  `start(x)`, `start(x) <- value`: Get or set `start(ranges(x))`.

  `end(x)`, `end(x) <- value`: Get or set `end(ranges(x))`.

  `width(x)`, `width(x) <- value`: Get or set `width(ranges(x))`.

  `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, pruning.mode=c("error", "coarse", "fine", "tidy")) <- 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 GRangesList 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.

### Coercion

In the code snippets below, `x` is a GRangesList 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, "IRangesList")`: Turns `x` into an IRangesList object.

When `x` is a `list` of `GRanges`, it can be coerced to a `GRangesList`.

  `as(x, "GRangesList")`: Turns `x` into a `GRangesList`.

### Subsetting

In the following code snippets, `x` is a GRangesList 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 GRangesList object. If `n` is negative, returns all but the last `abs(n)` elements of the GRangesList 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 GRanges object. If `n` is negative, returns all but the first `abs(n)` elements of the GRanges object.

### Combining

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

  `c(x, ...)`: Combines `x` and the GRangesList 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 GRanges object.

### Looping

In the code snippets below, `x` is a GRangesList 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 GRangesList 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 GRangesList objects.

  `mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE)`: Like the standard `mapply` function defined in the base package, the `mapply` method for GRangesList 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 GRangesList objects is a user-friendly version of `lapply` by default returning a vector or matrix if appropriate.

### Author(s)

P. Aboyoun & H. Pagès

### See Also

GRanges-class, `seqinfo`, Vector-class, RangesList-class, RleList-class, DataFrameList-class, intra-range-methods, inter-range-methods, coverage-methods, setops-methods, findOverlaps-methods

### Examples

    ## Construction with GRangesList():
    gr1 <-
      GRanges(seqnames = "chr2", ranges = IRanges(3, 6),
              strand = "+", score = 5L, GC = 0.45)
    gr2 <-
      GRanges(seqnames = c("chr1", "chr1"),
              ranges = IRanges(c(7,13), width = 3),
              strand = c("+", "-"), score = 3:4, GC = c(0.3, 0.5))
    gr3 <-
      GRanges(seqnames = c("chr1", "chr2"),
              ranges = IRanges(c(1, 4), c(3, 9)),
              strand = c("-", "-"), score = c(6L, 2L), GC = c(0.4, 0.1))
    grl <- GRangesList("gr1" = gr1, "gr2" = gr2, "gr3" = gr3)
    grl

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

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

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

    ## Coerce to IRangesList (seqnames and strand information is lost):
    as(grl, "IRangesList")

    ## isDisjoint():
    isDisjoint(grl)

    ## disjoin():
    disjoin(grl)  # metadata columns and order NOT preserved

    ## Construction with makeGRangesListFromFeatureFragments():
    filepath <- system.file("extdata", "feature_frags.txt",
                            package="GenomicRanges")
    featfrags <- read.table(filepath, header=TRUE, stringsAsFactors=FALSE)
    grl2 <- with(featfrags,
                 makeGRangesListFromFeatureFragments(seqnames=targetName,
                                                     fragmentStarts=targetStart,
                                                     fragmentWidths=blockSizes,
                                                     strand=strand))
    names(grl2) <- featfrags$RefSeqID
    grl2

[Package GenomicRanges version 1.30.3 Index]