# dist.circular: Distance Matrix Computation for Circular Data In circular: Circular Statistics

## 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

 `1` ```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.

`dist`