# Identify nearest member(s) in a set of intervals

### Description

For each point or interval in the `from`

argument,
identify the nearest member or members (in case of ties) of the
interval set in the `to`

argument.

### Usage

1 2 3 4 5 6 7 8 9 10 11 | ```
## S4 method for signature 'numeric,Intervals_virtual'
which_nearest(from, to, check_valid = TRUE)
## S4 method for signature 'Intervals_virtual,numeric'
which_nearest(from, to, check_valid = TRUE)
## S4 method for signature 'Intervals_virtual,Intervals_virtual'
which_nearest(from, to, check_valid = TRUE)
## S4 method for signature 'numeric,numeric'
which_nearest(from, to, check_valid = TRUE)
``` |

### Arguments

`from` |
An object of appropriate type. |

`to` |
An object of appropriate type. |

`check_valid` |
Should |

### Value

A data frame with three columns: `distance_to_nearest`

,
`which_nearest`

, and `which_overlap`

. The last two are
actually lists, since there may be zero, one, or more
nearest/overlapping intervals in the `to`

object for any given
interval in `from`

.

Empty intervals in `to`

, or intervals with `NA`

endpoints,
produce a `NA`

distance result, and no nearest or overlapping
hits.

### Note

(v. 0.11.0) The code used for the `distance_to_nearest`

column
here is completely distinct from that used for the original
`distance_to_nearest`

function. For the moment, they will
co-exist for testing purposes, but this function's code will
eventually replace the older code.

Note that a naive way of implementing `which_nearest`

would be to
use the simpler, old implementation of `distance_to_nearest`

, use
`expand`

to grow all intervals by the correspnoding amount, and
then use `interval_overlap`

to identify target. This approach,
however, will miss a small fraction of targets due to floating point
issues.

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ```
# Point to interval. Empty rows, or those with NA endpoints, do not
# generate hits. Note that distance_to_nearest can be 0 but without
# overlap, depending on endpoint closure.
to <- Intervals_full( c(-1,0,NA,5,-1,3,10,Inf) )
closed(to)[1,] <- FALSE
closed(to)[2,2] <- FALSE
from <- c( NA, -3:5 )
to
cbind( from, which_nearest( from, to ) )
# Completely empty to object
which_nearest( from, to[1,] )
# Interval to interval
from <- Intervals( c(-Inf,-Inf,3.5,-1,1,4) )
from
which_nearest( from, to )
# Checking behavior with ties
from <- Intervals_full( c(2,2,4,4,3,3,5,5) )
closed( from )[2:3,] <- FALSE
to <- Intervals_full( c(0,0,6,6,1,1,7,8) )
closed( to )[2:3,] <- FALSE
from
to
which_nearest( from, to )
from <- Intervals_full( c(1,3,6,2,4,7) )
to <- Intervals_full( c(4,4,5,5) )
closed( to )[1,] <- FALSE
from
to
which_nearest( from, to )
``` |