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 distances are calculated based on spherical law of cosines. Care is needed for ‘zero’ distances due to the final acosin: `acos(1-1e-16)`, especially with an actual radius.

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

There are many other packages providing distance functions. Especially for great circle distances there are considerable differences between the implementations. For high precision results, `sp::spDists` is a good candidate.

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

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

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.2-2 Index]