nearest               package:GenKern               R Documentation

_I_n_d_e_x _o_f _a _v_e_c_t_o_r _n_e_a_r_e_s_t _i_n _v_a_l_u_e _t_o _a _s_u_p_p_l_i_e_d _v_a_l_u_e

_D_e_s_c_r_i_p_t_i_o_n:

     Returns the index of a vector which contains the value closest to
     an arbitary value

_U_s_a_g_e:

     nearest(x, xval, outside=FALSE, na.rm=FALSE)

_A_r_g_u_m_e_n_t_s:

       x: vector of values

    xval: value to find the nearest value in `x' to

outside=FALSE: if not set to TRUE the function returns an error if
          `xval' is outside the range of `x'

   na.rm: NA behaviour: `TRUE' drops cases with NA's, `FALSE' stops
          function with a warning if NA's are detected: default=`FALSE'

_V_a_l_u_e:

     returns an integer: 

   index: the index of `x' with the value nearest to `xval'

_A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s:

     Written in collaboration with A.M.Pollard
     <a.m.pollard@bradford.ac.uk> with the financial support of the
     Natural Environment Research Council (NERC) grant GR3/11395

_N_o_t_e:

     The vector doesn't have to be in any particular order - this
     routine will just give the index of the nearest number. The only
     inconsistancy is that if the value of `xval' are not strictly
     within the range of the vector the function will return an error.
     To prevent this call with the `outside=TRUE' flag enabled. If
     there are many values which match the 'nearest' value then the
     function will return a vector of their indicies.

_A_u_t_h_o_r(_s):

     David Lucy <d.j.lucy@bradford.ac.uk> 
     Robert Aykroyd <robert@amsta.leeds.ac.uk><URL:
     http://www.amsta.leeds.ac.uk/~robert/>

_E_x_a_m_p_l_e_s:

     # make up a vector
     x <- c(1,2,2,2,2,2,3,4,5,6,7,8,9,10)
     # conventional useage - xval within range should return 9
     nearest(x, 4.7)
     # xval - outside the range of x should return 14
     nearest(x, 12.7, outside=TRUE)
     # many 'nearest' values in x - should return - 2 3 4 5 6 
     nearest(x, 1.7)
     # make x[3] an NA
     x[3] <- NA
     # returns - 2 4 5 6 - by enabling na.rm
     nearest(x, 1.7, na.rm=TRUE)

