nearestdist               package:spam               R Documentation

_D_i_s_t_a_n_c_e _M_a_t_r_i_x _C_o_m_p_u_t_a_t_i_o_n

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

     This function computes and returns specific elements of distance
     matrix computed by using the specified distance measure.

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

     nearest.dist( x, y=NULL, method = "euclidean",
                  eps = .Spam$eps, delta = 1,
                  diag = FALSE, upper = FALSE,
                  p=2, miles=TRUE, R=NULL)

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

       x: Matrix of first set of locations where each row gives the
          coordinates of a particular point. See also Details.

       y: Matrix of second set of locations where each row gives the
          coordinates of a particular point. If this is missing 'x' is
          used. See also Details.

  method: the distance measure to be used. This must be one of
          '"euclidean"', '"maximum"', '"minkowski"' or '"greatcircle"'.
          Any unambiguous substring can be given.

     eps: distances smaller than this number are considered zero.

   delta: only distances smaller than 'delta' are recorded.

    diag: Should the diagonal be included? See details.

   upper: Should the entire matrix ('NULL') or only the upper-triagonal
          ('TRUE') or lower-triagonal ('FALSE') values be calculated.

       p: The power of the Minkowski distance.

   miles: For great circle distance: If true distances are in statute
          miles if false distances in kilometers.

       R: For great circle distance: Radius to use for sphere to find
          spherical distances. If 'NULL' the radius is either in miles
          or kilometers depending on the values of the miles argument.
          If 'R=1' then distances are of course in radians.

_D_e_t_a_i_l_s:

     For great circle distance, the by 2 matrices 'x' and 'y' contain
     the degrees longitudes in the first and the degrees latitudes in
     the second column. 'eps' and 'delta' are in degrees. The distance
     is in single precision (I am still not sure where I loose the
     double in the Fortran code) and if calculating the entire matrix
     'upper=NULL' (instead of adding its transpose) it may not pass the
     symmetry checks, for example.


     The argument 'dist=TRUE' determines if diagonal elements will also
     be included if smaller than 'eps'. This is useful when calculating
     covariance matrices based on a distance matrix. The default values
     of 'dist=FALSE' and 'upper=FALSE' are borrowed from 'dist'.

     'x' and 'y' can be any object with an existing 'as.matrix' method.

     A quick scan revieled distance functions in at least 7 packages.
     The argument names should be as general as possible and be
     coherend with many (but not all) available distance functions.

     The Fortran code is based on a idea of Doug Nychka.

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

     A 'spam' object containing the distances spanned by 'eps' and
     'delta'.

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

     Reinhard Furrer

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

     # Note that upper=T and using t(X)+X is quicker than upper=NULL;
     #     upper=T marginally slower than upper=F.

     # To compare nearest.dist with dist, use diag=FALSE, upper=TRUE
     nx <- 4
     x <- expand.grid(as.double(1:nx),as.double(1:nx))
     sum( (nearest.dist( x, delta=nx*2, diag=FALSE, upper=TRUE)@entries-
                   c(dist(x)))^2)

     # Create nearest neighbor structures:
     par(mfcol=c(1,2))
     x <- expand.grid(1:nx,1:(2*nx))
     display( nearest.dist( x, delta=1))
     x <- expand.grid(1:(2*nx),1:nx)
     display( nearest.dist( x, delta=1))

