pMEM (version 0.1-1)

genDistMetric: Distance Metric Function Generator

Description

Function genDistMetric generates a distance metric function, which calculate pairwise distance values on the basis of given arguments.

Usage

genDistMetric(delta, theta = 0)

Value

A two-argument function (x and y) calculating the distances between the rows of x and the rows of y. When y is omitted, the pairwise distances between the rows of x are calculated instead.

Arguments

delta

Optional: the asymmetry parameter of the distance metric.

theta

The influence angle of the distance metric (default: 0).

Author

tools:::Rd_package_author("pMEM")

Details

When argument delta is omitted, the returned function calculates the Euclidean distance, whereas when is it provided with a value, the returned function calculates a complex-values distance metric whose modulus is the Euclidean distance and argument is related with delta. For one-dimensional data (transects), the argument is ±delta, with negative value for every second object located before the first, and positive values for every second object located after the first. For two-dimensional data, the value of the argument is the cosine of the angular difference between the angle of the line traversing the two points, defined in the direction going from the first to the second point, and the influence angle. In any case, the argument of the distance metric from a point A to a point B has the opposite sign as that of the distance metric from point B to point A. Therefore, the pairwise distance matrix is Hermitian and, as such, has eigenvalues that are strictly real-valued.

It is noteworthy that genDistMetric does not calculate the distances directly, as is the most common workflow, but generate a function that calculate the metric on the basis of the specified parameters (arguments delta and theta). The values of these parameters are embedded together with distance metric function in the returned object's namespace and can only be changed by generating a new function.

Examples

 ## A five point equidistant transect:
n <- 5
x <- (n - 1)*seq(0, 1, length.out=n)

## The symmetric (Euclidean metric) function is obtained by calling
## the generator function with not arguments as follows:
mSym <- genDistMetric()

## The pairwise symmetric metric between the rows of x:
mSym(x)

## A second set of points in the same range as the previous one, but at a
## distance of 0.05 from one another:
xx <- (n - 1)*seq(0, 1, 0.05)

## The same metrix, but between x and xx:
mSym(x,xx)

## The asymmetric function with a delta of 0.2:
mAsy <- genDistMetric(0.2)

## The pairwise asymmetric metric between the rows of x:
mAsy(x)

## The same metrix, but between x and xx:
mAsy(x,xx)