mapCoords-methods: Mapping ranges between sequences

Description

A method for translating a set of input ranges through a GRangesList object. Returns a GenomicRanges object.

NOTE: The mapCoords generic function is defined and documented in the IRanges package. A method for translating a set of input ranges through a GAlignments object is defined and documented in the GenomicAlignments package.

Usage

"mapCoords"(x, to, ...,  ignore.strand = FALSE, elt.loc = FALSE, elt.hits = FALSE)

Arguments

The input ranges to map, usually a GRanges.

The alignment between the sequences in x and the sequences in the result, usually a GRangesList.

ignore.strand

logical; When TRUE strand is ignored in overlap operations.

elt.loc

logical; When TRUE the location in the individual list elements is returned as metadata column eltLoc. For example, if to is a GRangesList of coding regions by transcript eltLoc is the position relative to each individual coding region. In contrast, the range in the output GRanges is the position relative to the transcript, i.e., coding regions are concatenated.

elt.hits

logical; When TRUE the indices of the unlisted to hit by x in the overlap operation are returned as metadata column eltHits. Internal use only.

...

Arguments passed to other methods.

Value

A GRanges object of mapped coordinates with matching data as metadata columns queryHits and subjectHits. Matching data are the result of calling findOverlaps with type `within` on ranges in x (the query) and the ranges in to (the subject). Matching can be many-to-one or one-to-many; one row is reported for each match.Optional metadata columns are eltLoc and eltHits, see arguments section for details. The ranges in the output GRanges are position relative to the outer list element of to; all individual list elements are concatenated and counting starts at the 5' or 3' end depending on strand. In contrast, the eltLoc metadata column contains position relative to the individual list elements.

Details

Each element in to is taken to represent an alignment of a sequence on a genome. The typical case is a set of transcript models, as might be obtained via GenomicFeatures::exonsBy. Each outer list element of the GRangesList represents a transcript while each each individual element is an exon in the transcript.

mapCoords translates the ranges in x relative to the transcript start. The widths of the individual elements (i.e., exons) are concatenated and counting starts at the 5' or 3' end depending on strand. Translated coordinates are only reported for ranges in x that fall completely `within` ranges in to.

The transcript-centric coordinates are are useful, for example, when predicting coding consequences of changes to the genomic sequence. Additionally, the position of x relative to the individual element (i.e., exon) is returned as a metadata column when elt.loc = TRUE.

Examples

Run this code

library(TxDb.Dmelanogaster.UCSC.dm3.ensGene)
txdb <- TxDb.Dmelanogaster.UCSC.dm3.ensGene
gr <- GRanges("chr2L", IRanges(c(7500, 8400, 9000), width = 200,
              names = LETTERS[1:3]))

## Coding region coordinates relative to transcript:
cdsbytx <- cdsBy(txdb, "tx")
map1 <- mapCoords(gr, cdsbytx)
map1

## Range A is not translated because it does not fall completely 
## 'within' any ranges.
findOverlaps(gr["A"], cdsbytx, type = "any")
findOverlaps(gr["A"], cdsbytx, type = "within")

## Exon region coordinates relative to trancript:
exonsbytx <- exonsBy(txdb, "tx")
map2 <- mapCoords(gr, exonsbytx)

## Add exon coordinates relative to the individual exons:
map3 <- mapCoords(gr, exonsbytx, elt.hits=TRUE, elt.loc=TRUE) 
map3

## Extract the individual exons hit:
unlist(exonsbytx, use.names=FALSE)[mcols(map3)$eltHits]