Package 'riemannianStats'

Plot a Riemannian Biplot

Description

Generates a biplot showing individuals on the principal plane and variables as arrows projected onto the same component space.

Usage

riem.biplot(
  data,
  components,
  correlations,
  clusters = NULL,
  explained.inertia = 0,
  title = "",
  var.scale = NULL,
  point.size = 2,
  alpha = 1,
  show.ind.labels = TRUE,
  show.var.labels = TRUE,
  ind.label.size = 3,
  var.label.size = 3,
  arrow.size = 0.4,
  var.color = "red",
  interactive = FALSE
)

Arguments

data	A data frame containing the original data. Row names are used as individual labels and column names are used as variable labels.
components	A matrix or data frame containing at least two components. The first two columns are used to represent individuals on the principal plane.
correlations	A matrix or data frame containing the correlations between variables and components. The first two columns are used to draw the variable arrows.
clusters	Optional vector of cluster labels used to color individuals according to the cluster they belong to.
explained.inertia	Numeric percentage of inertia explained by the plotted components. Defaults to '0'.
title	Optional character string added above the default title.
var.scale	Numeric scaling factor for variable arrows. Defaults to 'NULL', which automatically scales arrows to the individual plane.
point.size	Numeric size of the points. Defaults to '2'.
alpha	Numeric transparency value between 0 and 1. Defaults to '1'.
show.ind.labels	Logical. If 'TRUE', displays individual labels. Defaults to 'TRUE'.
show.var.labels	Logical. If 'TRUE', displays variable labels. Defaults to 'TRUE'.
ind.label.size	Numeric size of individual labels. Defaults to '3'.
var.label.size	Numeric size of variable labels. Defaults to '3'.
arrow.size	Numeric line width for variable arrows. Defaults to '0.4'.
var.color	Character string indicating the color of variable arrows and variable labels. Defaults to '"red"'.
interactive	Logical. If 'TRUE', returns an interactive 'plotly' plot. If 'FALSE', returns a static 'ggplot2' plot. Defaults to 'FALSE'.

Details

The biplot combines two types of information: the position of the individuals on the first two Riemannian components and the contribution of the variables represented as arrows. This allows the user to explore both the structure of the observations and the relationship between variables and components.

If 'interactive = TRUE', the static 'ggplot2' object is converted into an interactive 'plotly' object. In that case, hovering over the points displays information about the individuals, while hovering over the variable arrows or labels displays information about the corresponding variables.

Value

If 'interactive = FALSE', a 'ggplot' object. If 'interactive = TRUE', a 'plotly' object.

Examples

# Static biplot
data <- iris[, 1:4]
components <- prcomp(data, scale. = TRUE)$x
correlations <- cor(data, components[, 1:2])
riem.biplot(
  data = data,
  components = components,
  correlations = correlations,
  show.ind.labels = FALSE
)

# Interactive biplot
riem.biplot(
  data = data,
  components = components,
  correlations = correlations,
  show.ind.labels = FALSE,
  interactive = TRUE
)

---

Center Data Around the Riemannian Mean Observation

Description

Centers a dataset with respect to the Riemannian mean observation, defined as the row with the smallest total UMAP-based distance to all other rows.

Usage

riem.center.data(data, rho, umap.distance.matrix)

Arguments

data	A numeric data frame or matrix.
rho	A square numeric Rho matrix.
umap.distance.matrix	A square numeric UMAP-based distance matrix.

Value

A numeric matrix of Riemannian-centered data.

Examples

data <- iris[1:5, 1:4]
rho <- matrix(1, nrow = 5, ncol = 5)
dist.matrix <- as.matrix(dist(data))
centered <- riem.center.data(data, rho, dist.matrix)
head(centered)

---

Calculate the Riemannian Correlation Matrix

Description

Calculates the Riemannian correlation matrix from a numeric data frame or matrix, a Rho matrix, and a UMAP-based distance matrix.

Usage

riem.cor(data, rho, umap.distance.matrix)

Arguments

data	A numeric data frame or matrix where rows are observations and columns are variables.
rho	A numeric Rho matrix.
umap.distance.matrix	A numeric UMAP-based distance matrix.

Value

A numeric Riemannian correlation matrix.

Examples

data <- iris[, 1:4]
similarities <- riem.similarities.umap(data, n.neighbors = 5)
rho <- riem.rho(similarities)
riemannian.diff <- riem.diff(data = data, rho = rho)
distance.matrix <- riem.dist(riemannian.diff)

correlation.matrix <- riem.cor(
  data = data,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

---

Calculate a Riemannian Covariance Matrix

Description

Calculates a covariance matrix using Riemannian-centered differences with respect to the Riemannian mean observation.

Usage

riem.cov(data, rho, umap.distance.matrix, unbiased = FALSE)

Arguments

data	A numeric data frame or matrix.
rho	A square numeric Rho matrix.
umap.distance.matrix	A square numeric UMAP-based distance matrix.
unbiased	Logical. If 'TRUE', divides by 'n - 1'; otherwise divides by 'n'. Defaults to 'FALSE'.

Value

A numeric Riemannian covariance matrix.

Examples

data <- iris[1:10, 1:4]
similarities <- diag(nrow(data))
rho <- riem.rho(similarities)
diffs <- riem.diff(data, rho)
dist.matrix <- riem.dist(diffs)
riem.cov(data, rho, dist.matrix)

---

Calculate Riemannian Vector Differences

Description

Calculates weighted pairwise vector differences between all rows of a numeric dataset using the Rho matrix.

Usage

riem.diff(data, rho)

Arguments

data	A numeric data frame or matrix where rows are observations and columns are variables.
rho	A square numeric matrix with the same number of rows as 'data'.

Value

A three-dimensional numeric array. Entry '[i, j, ]' contains 'rho[i, j] * (data[i, ] - data[j, ])'.

Examples

data <- iris[1:5, 1:4]
rho <- matrix(1, nrow = 5, ncol = 5)
diffs <- riem.diff(data, rho)
dim(diffs)

---

Calculate the UMAP-Based Distance Matrix

Description

Calculates a pairwise distance matrix from a tensor of Riemannian vector differences.

Usage

riem.dist(riemannian.diff)

Arguments

riemannian.diff

A three-dimensional array where entry '[i, j, ]' contains the weighted vector difference between observations 'i' and 'j'.

Value

A square numeric distance matrix.

Examples

data <- iris[1:5, 1:4]
rho <- matrix(1, nrow = 5, ncol = 5)
diffs <- riem.diff(data, rho)
riem.dist(diffs)

---

Calculate Riemannian Principal Components

Description

Performs Riemannian principal component analysis from a numeric data frame or matrix, a Riemannian correlation matrix, a Rho matrix, and a UMAP-based distance matrix.

Usage

riem.ind.coord(
  data,
  correlation.matrix,
  rho,
  umap.distance.matrix,
  sign.convention = c("largest.negative", "largest.positive", "none")
)

Arguments

data	A numeric data frame or matrix where rows are observations and columns are variables.
correlation.matrix	A square numeric correlation matrix.
rho	A numeric Rho matrix.
umap.distance.matrix	A numeric UMAP-based distance matrix.
sign.convention	Character string indicating how to orient the signs of the eigenvectors. Options are '"largest.negative"', '"largest.positive"', and '"none"'. Defaults to '"largest.negative"'.

Details

The sign of principal components is arbitrary. This function uses a sign convention to make component orientations reproducible.

Value

A numeric matrix of Riemannian principal components.

Examples

data <- iris[, 1:4]
similarities <- riem.similarities.umap(data, n.neighbors = 5)
rho <- riem.rho(similarities)
riemannian.diff <- riem.diff(data, rho = rho)
distance.matrix <- riem.dist(riemannian.diff)

correlation.matrix <- riem.cor(
  data = data,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

components <- riem.ind.coord(
  data = data,
  correlation.matrix = correlation.matrix,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

head(components)

---

Calculate PCA Inertia for Two Components

Description

Calculates the proportion of total inertia, or explained variance, associated with two selected principal components from a correlation matrix.

Usage

riem.inertia(correlation.matrix, component1, component2)

Arguments

correlation.matrix	A square numeric correlation matrix.
component1	Integer index of the first selected component.
component2	Integer index of the second selected component.

Details

In R, component indices start at 1. Therefore, the first principal component is 'component1 = 1', not 'component1 = 0'.

Value

A numeric value between 0 and 1.

Examples

data <- iris[, 1:4]
similarities <- riem.similarities.umap(data, n.neighbors = 5)
rho <- riem.rho(similarities)
riemannian.diff <- riem.diff(data, rho = rho)
distance.matrix <- riem.dist(riemannian.diff)

correlation.matrix <- riem.cor(
  data = data,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

components <- riem.ind.coord(
  data = data,
  correlation.matrix = correlation.matrix,
  rho = rho,
  umap.distance.matrix = distance.matrix
)
riem.inertia(correlation.matrix, component1 = 1, component2 = 2)

---

Find the Riemannian Mean Observation Index

Description

Returns the index of the observation with the smallest total distance to all other observations.

Usage

riem.mean.index(umap.distance.matrix)

Arguments

umap.distance.matrix

A square numeric distance matrix.

Value

An integer index. In R, indexing starts at 1.

Examples

d <- as.matrix(dist(iris[1:5, 1:4]))
riem.mean.index(d)

---

Calculate the Euclidean Norm

Description

Calculates the Euclidean norm of a vector or the Euclidean distance between two vectors.

Usage

riem.norm(x, y = NULL)

Arguments

x	Numeric vector.
y	Optional numeric vector. If supplied, the norm of 'x - y' is computed.

Value

A single numeric value.

Examples

riem.norm(c(3, 4))
riem.norm(c(1, 2), c(4, 6))

---

Plot Riemannian Results

Description

Plots either the principal plane for individuals or the correlation circle for variables.

Usage

riem.plot(
  data,
  choix = c("ind", "var"),
  components = NULL,
  correlations = NULL,
  clusters = NULL,
  explained.inertia = 0,
  title = "",
  ...
)

Arguments

data	A numeric data frame or matrix.
choix	Character. Either '"ind"' for the principal plane or '"var"' for the correlation circle.
components	A matrix or data frame containing the coordinates of the individuals on the components. Required when 'choix = "ind"'.
correlations	A matrix or data frame containing the correlations between variables and components. Required when 'choix = "var"'.
clusters	Optional vector of cluster labels used to color individuals according to the cluster they belong to. Used only when 'choix = "ind"'.
explained.inertia	Numeric percentage of inertia explained by the plotted components. Defaults to '0'.
title	Optional character string added above the default title.
...	Additional arguments passed to the selected plotting function.

Value

A 'ggplot' object.

Examples

data <- iris[, 1:4]
components <- prcomp(data, scale. = TRUE)$x
correlations <- cor(data, components[, 1:2])

riem.plot(
  data = data,
  choix = "ind",
  components = components
)

riem.plot(
  data = data,
  choix = "var",
  correlations = correlations
)

---

Plot a Three-Dimensional Scatter Plot

Description

Creates an interactive three-dimensional scatter plot from selected columns of a data frame. Points can optionally be colored according to a cluster column.

Usage

riem.plot.3d(
  data,
  x.col,
  y.col,
  z.col,
  cluster.col = NULL,
  label.col = NULL,
  title = "",
  explained.inertia = 0,
  point.size = 5,
  alpha = 1
)

Arguments

data	A data frame containing the variables to plot.
x.col	Character string with the name of the x-axis column.
y.col	Character string with the name of the y-axis column.
z.col	Character string with the name of the z-axis column.
cluster.col	Optional character string with the name of the cluster column. If provided, points are colored according to the cluster they belong to. Defaults to 'NULL'.
label.col	Optional character string with the name of the column used as individual labels. If 'NULL', row names are used. Defaults to 'NULL'.
title	Optional character string added above the default title.
explained.inertia	Numeric percentage of inertia explained by the plotted components. Defaults to '0'.
point.size	Numeric size of the markers. Defaults to '5'.
alpha	Numeric transparency value between 0 and 1. Defaults to '1'.

Details

This function requires the optional package 'plotly'.

Value

A 'plotly' htmlwidget.

Examples

riem.plot.3d(
  data = iris,
  x.col = "Sepal.Length",
  y.col = "Sepal.Width",
  z.col = "Petal.Length"
)

riem.plot.3d(
  data = iris,
  x.col = "Sepal.Length",
  y.col = "Sepal.Width",
  z.col = "Petal.Length",
  cluster.col = "Species"
)

---

Calculate the Rho Matrix

Description

Calculates the Rho matrix as one minus the UMAP similarity matrix.

Usage

riem.rho(umap.similarities)

Arguments

umap.similarities

A numeric matrix of UMAP graph similarities.

Details

The Rho matrix is used to weight pairwise vector differences in the Riemannian analysis pipeline.

Value

A numeric matrix computed as '1 - umap.similarities'.

Examples

similarities <- diag(3)
riem.rho(similarities)

---

Calculate UMAP Graph Similarities

Description

Calculates a dense matrix of UMAP graph similarities from the local neighborhood graph of a numeric dataset.

Usage

riem.similarities.umap(
  data,
  n.neighbors = 3,
  min.dist = 0.1,
  metric = "euclidean",
  sparse = FALSE
)

Arguments

data	A numeric data frame or matrix where rows are observations and columns are variables.
n.neighbors	Integer. Number of nearest neighbors used to construct the local graph. Defaults to '3'.
min.dist	Numeric. Kept for API compatibility with UMAP workflows. The similarity graph itself is driven by local neighborhoods and the distance metric. Defaults to '0.1'.
metric	Character string. Distance metric used by UMAP. Defaults to '"euclidean"'.
sparse	Logical. If 'TRUE', returns the sparse graph returned by 'uwot'; if 'FALSE', returns a dense matrix. Defaults to 'FALSE'.

Details

This function is the R equivalent of extracting 'reducer.graph_' from 'umap-learn' in Python and converting it to a dense matrix.

Value

A numeric matrix or sparse matrix of UMAP similarities.

Examples

similarities <- riem.similarities.umap(
  iris[, 1:4],
  n.neighbors = 5
)
dim(similarities)

---

Calculate Riemannian Correlations Between Variables and Components

Description

Calculates Riemannian correlations between the original variables and the first two principal components.

Usage

riem.var.coord(data, components, rho, umap.distance.matrix)

Arguments

data	A numeric data frame or matrix where rows are observations and columns are variables.
components	A numeric matrix or data frame with at least two columns.
rho	A numeric Rho matrix.
umap.distance.matrix	A numeric UMAP-based distance matrix.

Value

A data frame with columns 'Component.1' and 'Component.2'.

Examples

data <- iris[, 1:4]
similarities <- riem.similarities.umap(data, n.neighbors = 5)
rho <- riem.rho(similarities)
riemannian.diff <- riem.diff(data, rho = rho)
distance.matrix <- riem.dist(riemannian.diff)

correlation.matrix <- riem.cor(
  data = data,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

components <- riem.ind.coord(
  data = data,
  correlation.matrix = correlation.matrix,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

correlations <- riem.var.coord(
  data = data,
  components = components,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

---