| Type: | Package |
| Title: | Riemannian Statistics for Dimensionality Reduction and Visualization |
| Version: | 0.1.1 |
| Description: | Provides tools for applying statistical methods on Riemannian manifolds using local geometry derived from Uniform Manifold Approximation and Projection (UMAP). The package enables dimensionality reduction, visualization, and analysis of complex data through Riemannian versions of principal component analysis and related multivariate methods. Methods are based on McInnes et al. (2018) <doi:10.21105/joss.00861>. |
| License: | BSD_3_clause + file LICENSE |
| Encoding: | UTF-8 |
| Language: | en-US |
| Depends: | R (≥ 4.1) |
| Imports: | rlang, ggplot2, ggrepel, grid, uwot |
| Suggests: | scatterplot3d, plotly, testthat (≥ 3.0.0), knitr, rmarkdown |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr, rmarkdown |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-08 16:34:20 UTC; r3291508 |
| Author: | Oldemar Rodríguez Rojas [aut, cre], Jennifer Lobo Vásquez [aut] |
| Maintainer: | Oldemar Rodríguez Rojas <oldemar.rodriguez@ucr.ac.cr> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-17 13:20:02 UTC |
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
)