genDistMetric {pMEM} | R Documentation |
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)
Arguments
delta |
Optional: the asymmetry parameter of the distance metric. |
theta |
The influence angle of the distance metric (default: 0). |
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.
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.
Author(s)
Guillaume Guénard [aut, cre] (ORCID: <https://orcid.org/0000-0003-0761-3072>), Pierre Legendre [ctb] (ORCID: <https://orcid.org/0000-0002-3838-3305>)
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)