join_nearest {plyranges} | R Documentation

## Find nearest neighbours between two Ranges objects

### Description

Find nearest neighbours between two Ranges objects

### Usage

    join_nearest(x, y, suffix = c(".x", ".y"))

    join_nearest_left(x, y, suffix = c(".x", ".y"))

    join_nearest_right(x, y, suffix = c(".x", ".y"))

    join_nearest_upstream(x, y, suffix = c(".x", ".y"))

    join_nearest_downstream(x, y, suffix = c(".x", ".y"))

### Arguments

`x, y` | Ranges objects, add the nearest neighbours of ranges in x to those in y.
`suffix` | A character vector of length two used to identify metadata columns coming from x and y.

### Details

By default `join_nearest` will find abritrary nearest neighbours in either direction and ignore any strand information. The `join_nearest_left` and `join_nearest_right` methods will find abritrary nearest neighbour ranges on x that are left/right of those on y and ignore any strand information.

The `join_nearest_upstream` method will find abritrary nearest neighbour ranges on x that are upstream of those on y. This takes into account strandedness of the ranges. On the positive strand nearest upstream will be on the left and on the negative strand nearest upstream will be on the right.

The `join_nearest_downstream` method will find abritrary nearest neighbour ranges on x that are upstream of those on y. This takes into account strandedness of the ranges.On the positive strand nearest downstream will be on the right and on the negative strand nearest upstream will be on the left.

### Value

A Ranges object corresponding to the nearest ranges, all metadata is copied over from the right-hand side ranges `y`.

### Examples

    query <- data.frame(start = c(5,10, 15,20),
                       width = 5,
                       gc = runif(4)) %>%
                 as_iranges()
    subject <- data.frame(start = c(2:6, 24),
                          width = 3:8,
                          label = letters[1:6]) %>%
                 as_iranges()

    join_nearest(query, subject)
    join_nearest_left(query, subject)
    join_nearest_right(query, subject)

    subject  <- data.frame(seqnames = "chr1",
                   start = c(11,101),
                   end = c(21, 200),
                   name = c("a1", "a2"),
                   strand = c("+", "-"),
                   score = c(1,2)) %>%
               as_granges()
    query <- data.frame(seqnames = "chr1",
                          strand = c("+", "-", "+", "-"),
                          start = c(21,91,101,201),
                          end = c(30,101,110,210),
                          name = paste0("b", 1:4),
                          score = 1:4) %>%
                       as_granges()
    join_nearest_upstream(query, subject)
    join_nearest_downstream(query, subject)

[Package plyranges version 1.4.4 Index]