R: Distance Matrix Computation

nearestdist {spam} | R Documentation

## Distance Matrix Computation

### Description

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

### Usage

    nearest.dist( x, y=NULL, method = "euclidean",
                 delta = 1, upper = if (is.null(y)) FALSE else NULL,
                 p=2, miles=TRUE, R=NULL)

### Arguments

`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.
`delta` | only distances smaller than `delta` are recorded, 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.

### Details

For great circle distance, the 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. Hence to restrict to distances smaller than `delta.km`, one has to specify `delta=delta.km*360/(6378.388*2*pi)`.

The distance is in single precision (I am still not sure where I lose the double precision 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.

Default value of Earth's radius is 3963.34miles (6378.388km).

The formerly depreciated arguments `eps` and `diag` are now eliminated.

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

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

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

### Value

A `spam` object containing the distances spanned between zero and `delta`. The sparse matrix may contain many zeros (e.g., collocated data). However, to calculate covariances, these zeros are essential.

### Author(s)

Reinhard Furrer

### See Also

`spam_rdist`

### Examples

    # 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 as.dist(...)
    nx <- 4
    x <- expand.grid(as.double(1:nx),as.double(1:nx))
    sum( ( as.dist(nearest.dist( x, delta=nx*2))-
              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))

[Package spam version 2.1-1 Index]