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

Description

The distance methods for TxDb objects and subclasses.

Usage

"distance"(x, y, ignore.strand=FALSE, ..., id, type=c("gene", "tx", "exon", "cds"))

Arguments

The query GenomicRanges instance.

For distance, a TxDb instance. The id is used to extract ranges from the TxDb which are then used to compute the distance from x.

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.

Value

For distance, an integer vector of distances between the ranges in x and y.

Details

distance: 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 behavior of distance has changed in Bioconductor 2.12. See the man page ?distance in IRanges for details.

Examples

Run this code

  ## -----------------------------------------------------------
  ## distance()
  ## -----------------------------------------------------------

  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)