absoluteRanges {GenomicRanges} | R Documentation

## Transform genomic ranges into "absolute" ranges

### Description

`absoluteRanges` transforms the genomic ranges in `x` into absolute ranges i.e. into ranges counted from the beginning of the virtual sequence obtained by concatenating all the sequences in the underlying genome (in the order reported by `seqlevels(x)`).

`relativeRanges` performs the reverse transformation.

NOTE: These functions only work on small genomes. See Details section below.

### Usage

    absoluteRanges(x)
    relativeRanges(x, seqlengths)

    ## Related utility:
    isSmallGenome(seqlengths)

### Arguments

`x` | For `absoluteRanges`: a GenomicRanges object with ranges defined on a small genome (see Details section below). For `relativeRanges`: an IntegerRanges object.
`seqlengths` | An object holding sequence lengths. This can be a named integer (or numeric) vector with no duplicated names as returned by `seqlengths()`, or any object from which sequence lengths can be extracted with `seqlengths()`. For `relativeRanges`, `seqlengths` must describe a small genome (see Details section below).

### Details

Because `absoluteRanges` returns the absolute ranges in an IRanges object, and because an IRanges object cannot hold ranges with an end > `.Machine$integer.max` (i.e. >= 2^31 on most platforms), `absoluteRanges` cannot be used if the size of the underlying genome (i.e. the total length of the sequences in it) is > `.Machine$integer.max`. Utility function `isSmallGenome` is provided as a mean for the user to check upfront whether the genome is small (i.e. its size is <= `.Machine$integer.max`) or not, and thus compatible with `absoluteRanges` or not.

`relativeRanges` applies the same restriction by looking at the `seqlengths` argument.

### Value

An IRanges object for `absoluteRanges`.

A GRanges object for `relativeRanges`.

`absoluteRanges` and `relativeRanges` both return an object that is parallel to the input object (i.e. same length and names).

`isSmallGenome` returns TRUE if the total length of the underlying sequences is <= `.Machine$integer.max` (e.g. Fly genome), FALSE if not (e.g. Human genome), or NA if it cannot be computed (because some sequence lengths are NA).

### Author(s)

H. Pagès

### See Also

- GRanges objects.

- IntegerRanges objects in the IRanges package.

- Seqinfo objects and the `seqlengths` getter in the GenomeInfoDb package.

- genomicvars for manipulating genomic variables.

- The `tileGenome` function for putting tiles on a genome.

### Examples

    ## ---------------------------------------------------------------------
    ## TOY EXAMPLE
    ## ---------------------------------------------------------------------

    gr <- GRanges(Rle(c("chr2", "chr1", "chr3", "chr1"), 4:1),
                  IRanges(1:10, width=5),
                  seqinfo=Seqinfo(c("chr1", "chr2", "chr3"), c(100, 50, 20)))

    ar <- absoluteRanges(gr)
    ar

    gr2 <- relativeRanges(ar, seqlengths(gr))
    gr2

    ## Sanity check:
    stopifnot(all(gr == gr2))

    ## ---------------------------------------------------------------------
    ## ON REAL DATA
    ## ---------------------------------------------------------------------

    ## With a "small" genome

    library(TxDb.Dmelanogaster.UCSC.dm3.ensGene)
    txdb <- TxDb.Dmelanogaster.UCSC.dm3.ensGene
    ex <- exons(txdb)
    ex

    isSmallGenome(ex)

    ## Note that because isSmallGenome() can return NA (see Value section
    ## above), its result should always be wrapped inside isTRUE() when
    ## used in an if statement:
    if (isTRUE(isSmallGenome(ex))) {
        ar <- absoluteRanges(ex)
        ar

        ex2 <- relativeRanges(ar, seqlengths(ex))
        ex2  # original strand is not restored

        ## Sanity check:
        strand(ex2) <- strand(ex)  # restore the strand
        stopifnot(all(ex == ex2))
    }

    ## With a "big" genome (but we can reduce it)

    library(TxDb.Hsapiens.UCSC.hg19.knownGene)
    txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene
    ex <- exons(txdb)
    isSmallGenome(ex)
    ## Not run:
        absoluteRanges(ex)  # error!

    ## End(Not run)

    ## However, if we are only interested in some chromosomes, we might
    ## still be able to use absoluteRanges():
    seqlevels(ex, pruning.mode="coarse") <- paste0("chr", 1:10)
    isSmallGenome(ex)  # TRUE!
    ar <- absoluteRanges(ex)
    ex2 <- relativeRanges(ar, seqlengths(ex))

    ## Sanity check:
    strand(ex2) <- strand(ex)
    stopifnot(all(ex == ex2))

[Package GenomicRanges version 1.42.0 Index]