inter-range-methods {GenomicRanges} | R Documentation

## Inter range transformations of a GRanges or GRangesList object

### Description

This man page documents inter range transformations of a GenomicRanges object (i.e. of an object that belongs to the GenomicRanges class or one of its subclasses, this includes for example GRanges objects), or a GRangesList object.

See `?`intra-range-methods`` and `?`inter-range-methods`` in the IRanges package for a quick introduction to intra range and inter range transformations.

See `?`intra-range-methods`` for intra range transformations of a GenomicRanges object or GRangesList object.

### Usage

    ## S4 method for signature 'GenomicRanges'
    range(x, ..., with.revmap=FALSE, ignore.strand=FALSE, na.rm=FALSE)
    ## S4 method for signature 'GRangesList'
    range(x, ..., with.revmap=FALSE, ignore.strand=FALSE, na.rm=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    range(x, ..., with.revmap=FALSE, ignore.strand=FALSE, na.rm=FALSE)

    ## S4 method for signature 'GenomicRanges'
    reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE,
              with.inframe.attrib=FALSE, ignore.strand=FALSE)
    ## S4 method for signature 'GRangesList'
    reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE,
              with.inframe.attrib=FALSE, ignore.strand=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    reduce(x, drop.empty.ranges=FALSE,
              min.gapwidth=1L, with.inframe.attrib=FALSE, ignore.strand=FALSE)

    ## S4 method for signature 'GenomicRanges'
    gaps(x, start=1L, end=seqlengths(x))

    ## S4 method for signature 'GenomicRanges'
    disjoin(x, with.revmap=FALSE, ignore.strand=FALSE)
    ## S4 method for signature 'GRangesList'
    disjoin(x, with.revmap=FALSE, ignore.strand=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    disjoin(x, with.revmap=FALSE, ignore.strand=FALSE)

    ## S4 method for signature 'GenomicRanges'
    isDisjoint(x, ignore.strand=FALSE)
    ## S4 method for signature 'GRangesList'
    isDisjoint(x, ignore.strand=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    isDisjoint(x, ignore.strand=FALSE)

    ## S4 method for signature 'GenomicRanges'
    disjointBins(x, ignore.strand=FALSE)

### Arguments

`x` | A GenomicRanges or GenomicRangesList object.
`drop.empty.ranges, min.gapwidth, with.revmap, with.inframe.attrib, start, end` | See `?`inter-range-methods`` in the IRanges package.
`ignore.strand` | `TRUE` or `FALSE`. Whether the strand of the input ranges should be ignored or not. See details below.
`...` | For `range`, additional `GenomicRanges` objects to consider. Ignored otherwise.
`na.rm` | Ignored.

### Details

#### On a GRanges object

`range` returns an object of the same type as `x` containing range bounds for each distinct (seqname, strand) pairing. The names (`names(x)`) and the metadata columns in `x` are dropped.

`reduce` returns an object of the same type as `x` containing reduced ranges for each distinct (seqname, strand) pairing. The names (`names(x)`) and the metadata columns in `x` are dropped. See `?reduce` for more information about range reduction and for a description of the optional arguments.

`gaps` returns an object of the same type as `x` containing complemented ranges for each distinct (seqname, strand) pairing. The names (`names(x)`) and the columns in `x` are dropped. For the start and end arguments of this gaps method, it is expected that the user will supply a named integer vector (where the names correspond to the appropriate seqlevels). See `?gaps` for more information about range complements and for a description of the optional arguments.

`disjoin` returns an object of the same type as `x` containing disjoint ranges for each distinct (seqname, strand) pairing. The names (`names(x)`) and the metadata columns in `x` are dropped. If `with.revmap=TRUE`, a metadata column that maps the ouput ranges to the input ranges is added to the returned object. See `?disjoin` for more information.

`isDisjoint` returns a logical value indicating whether the ranges in `x` are disjoint (i.e. non-overlapping).

`disjointBins` returns bin indexes for the ranges in `x`, such that ranges in the same bin do not overlap. If `ignore.strand=FALSE`, the two features cannot overlap if they are on different strands.

#### On a GRangesList/GenomicRangesList object

When they are supported on GRangesList object `x`, the above inter range transformations will apply the transformation to each of the list elements in `x` and return a list-like object parallel to `x` (i.e. with 1 list element per list element in `x`). If `x` has names on it, they're propagated to the returned object.

### Author(s)

H. Pagès and P. Aboyoun

### See Also

- The GenomicRanges and GRanges classes.

- The IntegerRanges class in the IRanges package.

- The inter-range-methods man page in the IRanges package.

- GenomicRanges-comparison for comparing and ordering genomic ranges.

- `endoapply` in the S4Vectors package.

### Examples

    gr <- GRanges(
            seqnames=Rle(paste("chr", c(1, 2, 1, 3), sep=""), c(1, 3, 2, 4)),
            ranges=IRanges(1:10, width=10:1, names=letters[1:10]),
            strand=Rle(strand(c("-", "+", "*", "+", "-")), c(1, 2, 2, 3, 2)),
            score=1:10,
            GC=seq(1, 0, length=10)
          )
    gr

    gr1 <- GRanges(seqnames="chr2", ranges=IRanges(3, 6),
                   strand="+", score=5L, GC=0.45)
    gr2 <- GRanges(seqnames="chr1",
                   ranges=IRanges(c(10, 7, 19), width=5),
                   strand=c("+", "-", "+"), score=3:5, GC=c(0.3, 0.5, 0.66))
    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

    ## ---------------------------------------------------------------------
    ## range()
    ## ---------------------------------------------------------------------

    ## On a GRanges object:
    range(gr)
    range(gr, with.revmap=TRUE)

    ## On a GRangesList object:
    range(grl)
    range(grl, ignore.strand=TRUE)
    range(grl, with.revmap=TRUE, ignore.strand=TRUE)

    # ---------------------------------------------------------------------
    ## reduce()
    ## ---------------------------------------------------------------------
    reduce(gr)

    gr2 <- reduce(gr, with.revmap=TRUE)
    revmap <- mcols(gr2)$revmap  # an IntegerList

    ## Use the mapping from reduced to original ranges to group the original
    ## ranges by reduced range:
    relist(gr[unlist(revmap)], revmap)

    ## Or use it to split the DataFrame of original metadata columns by
    ## reduced range:
    relist(mcols(gr)[unlist(revmap), ], revmap)  # a SplitDataFrameList

    ## [For advanced users] Use this reverse mapping to compare the reduced
    ## ranges with the ranges they originate from:
    expanded_gr2 <- rep(gr2, elementNROWS(revmap))
    reordered_gr <- gr[unlist(revmap)]
    codes <- pcompare(expanded_gr2, reordered_gr)
    ## All the codes should translate to "d", "e", "g", or "h" (the 4 letters
    ## indicating that the range on the left contains the range on the right):
    alphacodes <- rangeComparisonCodeToLetter(pcompare(expanded_gr2, reordered_gr))
    stopifnot(all(alphacodes %in% c("d", "e", "g", "h")))

    ## On a big GRanges object with a lot of seqlevels:
    mcols(gr) <- NULL
    biggr <- c(gr, GRanges("chr1", IRanges(c(4, 1), c(5, 2)), strand="+"))
    seqlevels(biggr) <- paste0("chr", 1:2000)
    biggr <- rep(biggr, 25000)
    set.seed(33)
    seqnames(biggr) <- sample(factor(seqlevels(biggr), levels=seqlevels(biggr)),
                              length(biggr), replace=TRUE)

    biggr2 <- reduce(biggr, with.revmap=TRUE)
    revmap <- mcols(biggr2)$revmap
    expanded_biggr2 <- rep(biggr2, elementNROWS(revmap))
    reordered_biggr <- biggr[unlist(revmap)]
    codes <- pcompare(expanded_biggr2, reordered_biggr)
    alphacodes <- rangeComparisonCodeToLetter(pcompare(expanded_biggr2,
                                                      reordered_biggr))
    stopifnot(all(alphacodes %in% c("d", "e", "g", "h")))
    table(alphacodes)

    ## On a GRangesList object:
    reduce(grl)  # Doesn't really reduce anything but note the reordering
                 # of the inner elements in the 2nd and 3rd list elements:
                 # the ranges are reordered by sequence name first (which
                 # should appear in the same order as in 'seqlevels(grl)'),
                 # and then by strand.
    reduce(grl, ignore.strand=TRUE)  # 2nd list element got reduced

    ## ---------------------------------------------------------------------
    ## gaps()
    ## ---------------------------------------------------------------------
    gaps(gr, start=1, end=10)

    ## ---------------------------------------------------------------------
    ## disjoin(), isDisjoint(), disjointBins()
    ## ---------------------------------------------------------------------
    disjoin(gr)
    disjoin(gr, with.revmap=TRUE)
    disjoin(gr, with.revmap=TRUE, ignore.strand=TRUE)
    isDisjoint(gr)
    stopifnot(isDisjoint(disjoin(gr)))
    disjointBins(gr)
    stopifnot(all(sapply(split(gr, disjointBins(gr)), isDisjoint)))

    ## On a GRangesList object:
    disjoin(grl)  # doesn't really disjoin anything but note the reordering
    disjoin(grl, with.revmap=TRUE)

[Package GenomicRanges version 1.36.1 Index]