nearest-methods: Finding the nearest genomic range neighbor in a TxDb

In Bioconductor/GenomicFeatures: Query the gene models of a given organism/assembly

Finding the nearest genomic range neighbor in a TxDb

Description

A distance() method for TxDb objects.

Usage

## S4 method for signature 'GenomicRanges,TxDb'
distance(x, y, ignore.strand=FALSE,
    ..., id, type=c("gene", "tx", "exon", "cds"))

Arguments

x	The query GenomicRanges instance.
y	A TxDb object. The id is used to extract ranges from the TxDb which are then used to compute the distance from x.
id	A character vector the same length as x. The id must be identifiers in the TxDb object. type indicates what type of identifier id is.
type	A character(1) describing the id. Must be one of ‘gene’, ‘tx’, ‘exon’ or ‘cds’.
ignore.strand	A logical indicating if the strand of the ranges should be ignored. When TRUE, strand is set to '+'.
...	Additional arguments for methods.

Details

This distance() method returns the distance for each range in x to the range extracted from the TxDb object y. Values in id are matched to one of ‘gene_id’, ‘tx_id’, ‘exon_id’ or ‘cds_id’ identifiers in the TxDb and the corresponding ranges are extracted. The type argument specifies which identifier is represented in id. The extracted ranges are used in the distance calculation with the ranges in x.

The method returns NA values when the genomic region defined by id cannot be collapsed into a single range (e.g., when a gene spans multiple chromosomes) or if the id is not found in y.

The behavior of distance() with respect to zero-width ranges has changed in Bioconductor 2.12. See the man page ?distance in the IRanges for details.

Value

An integer vector of distances between the ranges in x and y.

Author(s)

Valerie Obenchain <[e-mail]>

See Also

• nearest-methods in the IRanges package.

• nearest-methods in the GenomicRanges package.

Examples

library(TxDb.Dmelanogaster.UCSC.dm3.ensGene)
txdb <- TxDb.Dmelanogaster.UCSC.dm3.ensGene
gr <- GRanges(c("chr2L", "chr2R"),
              IRanges(c(100000, 200000),  width=100))
distance(gr, txdb, id=c("FBgn0259717", "FBgn0261501"), type="gene")
distance(gr, txdb, id=c("10000", "23000"), type="cds")

## The id's must be in the appropriate order with respect to 'x'.
distance(gr, txdb, id=c("4", "4097"), type="tx")

## 'id' "4" is on chr2L and "4097" is on chr2R.
transcripts(txdb, filter=list(tx_id=c("4", "4097")))

## If we reverse the 'id' the chromosomes are incompatable with gr.
distance(gr, txdb, id=c("4097", "4"), type="tx")

## distance() compares each 'x' to the corresponding 'y'.
## If an 'id' is not found in the TxDb 'y' will not
## be the same lenth as 'x' and an error is thrown.
## Not run: 
distance(gr, txdb, id=c("FBgn0000008", "INVALID"), type="gene") ## will fail

## End(Not run)

Bioconductor/GenomicFeatures documentation built on Nov. 7, 2024, 4:25 a.m.