R: Distance Matrix Computation for Circular Data

dist.circular {circular} | R Documentation

## Distance Matrix Computation for Circular Data

### Description

This function computes and returns the distance matrix computed by using the specified distance measure to compute the distances between the rows of a data matrix containing circular data.

### Usage

    dist.circular(x, method = "correlation", diag = FALSE, upper = FALSE)

### Arguments

`x` | a numeric matrix of class `circular`.
`method` | the distance measure to be used. This must be one of `"correlation"`, `"angularseparation"`, `"chord"`, `"geodesic"`. Any unambiguous substring can be given.
`diag` | logical value indicating whether the diagonal of the distance matrix should be printed by `print.dist`.
`upper` | logical value indicating whether the upper triangle of the distance matrix should be printed by `print.dist`.

### Details

Available distance measures are (written for two vectors x and y):

`correlation`:

  sqrt(1-rho) where rho is the Circular Correlation coefficient defined as

  sum(sin(x - mux)*sin(y - muy))/(sum(sin(x - mux)^2)*sum(sin(y - muy)^2))^(1/2)

  and mux, muy are the mean direction of the two vectors

`angularseparation`:

  sum(1 - cos(x - y))

`chord`:

  sum(sqrt(2 (1 - cos(x - y))))

`geodesic`:

  sum(pi - abs(pi - abs(x - y))) where the abs(x - y) is expressed with an angle in [-pi,pi]

Missing values are allowed, and are excluded from all computations involving the rows within which they occur. Further, when `Inf` values are involved, all pairs of values are excluded when their contribution to the distance gave `NaN` or `NA`.
If some columns are excluded in calculating the sum is scaled up proportionally to the number of columns used. If all pairs are excluded when calculating a particular distance, the value is `NA`.

### Value

`dist.circular` returns an object of class `"dist"`.

The lower triangle of the distance matrix stored by columns in a vector, say `do`. If `n` is the number of observations, i.e., `n <- attr(do, "Size")`, then for i < j <= n, the dissimilarity between (row) i and j is `do[n*(i-1) - i*(i-1)/2 + j-i]`. The length of the vector is n*(n-1)/2, i.e., of order n^2.

The object has the following attributes (besides `"class"` equal to `"dist"`):

`Size` | integer, the number of observations in the dataset.
`Labels` | optionally, contains the labels, if any, of the observations of the dataset.
`Diag, Upper` | logicals corresponding to the arguments `diag` and `upper` above, specifying how the object should be printed.
`call` | optionally, the `call` used to create the object.
`method` | optionally, the distance method used; resulting from `dist.circular()`, the (`match.arg()`ed) `method` argument.

### See Also

`dist`

[Package circular version 0.4-93 Index]