hydra (version 0.1.0)

hydra: Calculate hyperbolic embedding of distance data

Description

Implements the HYDRA (hyperbolic distance recovery and approximation) method for embedding high-dimensional data points (represented by their distance matrix D) into low-dimensional hyperbolic space.

Usage

hydra(D, dim = 2, curvature = 1, alpha = 1.1, equi.adj = 0.5,
  control = list())

Arguments

D

a square symmetric matrix of distances (or dissimiliarities) to be embdedded, can also be a dist object

dim

embedding dimension

curvature

embedding curvature; if this argument is NULL, hydra tries to find the optimal curvature

alpha

real number greater one; adjusts the hyperbolic curvature. Values larger than one yield a more distorted embedding where points are pushed to the outer boundary (i.e. the ideal points) of hyperblic space. The interaction between curvature and alpha is non-linear.

equi.adj

equi-angular adjustment; must be a real number between zero and one; only used if dim is 2. Value 0 means no ajustment, 1 adjusts embedded data points such that their angular coordinates in the Poincare disc are uniformly distributed. Other values interpolate between the two extremes. Setting the parameter to non-zero values can make the embedding result look more harmoniuous in plots.

control

a list which may contain the following boolean flags:

• polar - return polar coordinates in dimension 2 (default: TRUE if dim is 2. This flag is ignored in higher dimension)

• isotropic.adj - perform isotropic adjustment, ignoring Eigenvalues (default: TRUE if dim is 2, FALSE else)

• return.lorentz - return raw Lorentz coordinates (before projection to hyperbolic space) (default: FALSE)

• return.stress - return embedding stress (default: TRUE)

• return.dist - return hyperbolic distance matrix of embedded points (default: FALSE)

• use.eigs - use eigs function from RSpectra and norm function from Matrix to speed up computation (default: FALSE)

Value

A `hydra' object, which is a list with all or some of the following components:

r

a vector containing the radial coordinates of the embedded points

directional

a matrix with dim columns containing as rows the directional coordinates of the embedded points

theta

a vector containing the angular coordinates of the embedded points (only returned if dim is 2 and polar flag is TRUE)

curvature

the curvature used for the returned embedding

dim

the dimension used for the returned embedding

stress

the stress (i.e. the mean-square difference) between distances supplied in D and the hyperbolic distance matrix of the returned embedding

dist

the hyperbolic distance matrix of the returned embedding (only returned if flag return.dist is true. Computation may be time- and memory-intensive.)

x0

a vector containing the 'time-like' coordinate of the raw Lorentz embedding (only returned if flag return.lorentz is true)

X

a matrix with dim columns containing as rows the 'space-like' coordinate of the raw Lorentz embedding (only returned if flag return.lorentz is true)

Details

See https://arxiv.org/abs/1903.08977 for more details.

Examples

# NOT RUN {
data(karate)
embedding <- hydra(karate$distance)
plot(embedding,labels=karate$label,lab.col=karate$group,graph.adj=karate$adjacency)

## Compare with Multidimensional scaling (MDS):
mds <- cmdscale(karate$distance) # Compute Euclidean embedding with MDS
mds.stress <- sqrt(sum((as.matrix(dist(mds)) - karate$distance)^2)) # Calculate embedding stress
c(embedding$stress,mds.stress) # Compare hyperbolic with Euclidean stress

# }