Package {riemannianStats}

Extract Riemannian Regression Coefficients

Description

Extract Riemannian Regression Coefficients

Usage

## S3 method for class 'riem.lm'
coef(object, ...)

Arguments

Value

A named numeric vector of coefficients.

Extract Riemannian Fitted Values

Description

Extract Riemannian Fitted Values

Usage

## S3 method for class 'riem.lm'
fitted(object, ...)

Arguments

Value

A numeric vector of fitted values in the Riemannian transformed scale.

Print a Riemannian Linear Regression Model

Description

Print a Riemannian Linear Regression Model

Usage

## S3 method for class 'riem.lm'
print(x, ...)

Arguments

Value

Invisibly returns 'x'.

Print method for Riemannian PCA

Description

Print method for Riemannian PCA

Usage

## S3 method for class 'riem.pca'
print(x, ...)

Arguments

Value

Invisibly returns 'x'.

Print a Summary of a Riemannian Linear Regression Model

Description

Print a Summary of a Riemannian Linear Regression Model

Usage

## S3 method for class 'summary.riem.lm'
print(x, ...)

Arguments

Value

Invisibly returns 'x'.

Extract Riemannian Residuals

Description

Extract Riemannian Residuals

Usage

## S3 method for class 'riem.lm'
residuals(object, ...)

Arguments

Value

A numeric vector of residuals in the Riemannian transformed scale.

Riemannian PCA Biplot

Description

Creates a biplot from a Riemannian PCA object or from manually supplied coordinates.

Usage

riem.biplot(data, ...)

Arguments

Value

A biplot.

Default Method for Riemannian PCA Biplots

Description

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

Usage

## Default S3 method:
riem.biplot(
  data,
  components = NULL,
  correlations = NULL,
  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

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
)

Riemannian PCA Biplot

Description

Riemannian PCA Biplot

Usage

## S3 method for class 'riem.pca'
riem.biplot(data, axes = NULL, title = NULL, ...)

Arguments

Value

A biplot.

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

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

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

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

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 Distance Matrix

Description

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

Usage

riem.dist(riemannian.diff)

Arguments

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

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

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)

Riemannian Linear Regression

Description

Fits a Riemannian linear regression model using a similarity matrix induced by UMAP, Isomap or DBSCAN.

Usage

riem.lm(
  formula = NULL,
  data = NULL,
  y = NULL,
  na.action = stats::na.omit,
  similarities = c("umap", "isomap", "dbscan"),
  n.neighbors = 3,
  min.dist = NULL,
  metric = "euclidean",
  tol = 1e-10,
  verbose = FALSE,
  max.neighbors = NULL,
  sigma = NULL,
  eps = NULL,
  eps.quantile = 0.9,
  minPts = NULL,
  density.power = 1,
  between.cluster.factor = 0.05,
  noise.factor = 0.1,
  use.only.eps.neighborhood = FALSE
)

Arguments

Details

The function first constructs a similarity matrix using one of [riem.similarities.umap()], [riem.similarities.isomap()] or [riem.similarities.dbscan()]. Then, it computes the corresponding Riemannian dissimilarity matrix with [riem.rho()], obtains Riemannian differences with [riem.diff()], and selects the Riemannian mean index using [riem.mean.index()].

The regression is fitted after centering the explanatory variables and response around the Riemannian center and weighting the centered data using the Riemannian weights.

Value

An object of class '"riem.lm"', which is a list containing:

• 'beta.R': Riemannian regression coefficients.

• 'yhat.R': fitted values in the Riemannian transformed scale.

• 'y.R': response vector in the Riemannian transformed scale.

• 'residuals.R': residuals in the Riemannian transformed scale.

• 'R2.R': Riemannian coefficient of determination.

• 'lambda': index of the Riemannian mean observation.

• 'x.lambda': explanatory variables at the Riemannian center.

• 'y.lambda': response value at the Riemannian center.

• 'weights': Riemannian weights derived from 'rho'.

• 'similarities': similarity matrix.

• 'rho': Riemannian dissimilarity matrix.

• 'distance.matrix': Riemannian distance matrix.

Examples

model <- riem.lm(
  Sepal.Length ~ Sepal.Width + Petal.Length + Petal.Width,
  data = iris,
  similarities = "umap",
  n.neighbors = 5
)

model
coef(model)
summary(model)

original <- riem.original.scale(model)
head(original$table)

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

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

Value

A single numeric value.

Examples

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

Convert a Riemannian Regression Fit to the Original Scale

Description

Converts fitted values and residuals from a Riemannian regression model back to the original response scale.

Usage

riem.original.scale(object)

Arguments

Details

The fitted values stored in a '"riem.lm"' object are computed in the Riemannian transformed scale. This function reconstructs fitted values in the original response scale using the Riemannian center.

Value

A list containing original response values, fitted values, residuals, original-scale sums of squares, original-scale coefficients of determination and a data frame with observation-level results.

Examples

model <- riem.lm(
  data = iris[, 1:4],
  y = iris$Sepal.Length,
  similarities = "umap",
  n.neighbors = 5
)

original <- riem.original.scale(model)
head(original$table)

Riemannian Principal Component Analysis Riemannian Principal Component Analysis

Description

Performs Riemannian principal component analysis using a similarity matrix induced by UMAP, Isomap or DBSCAN.

Usage

riem.pca(
  data,
  scale.unit = TRUE,
  ncp = 5,
  axes = c(1, 2),
  n.neighbors = 3,
  min.dist = 0.1,
  metric = "euclidean",
  method = c("umap", "isomap", "dbscan"),
  verbose = FALSE,
  max.neighbors = NULL,
  sigma = NULL,
  eps = NULL,
  eps.quantile = 0.9,
  minPts = NULL,
  density.power = 1,
  between.cluster.factor = 0.05,
  noise.factor = 0.1,
  use.only.eps.neighborhood = FALSE
)

Arguments

Value

An object of class '"riem.pca"', which is a list containing:

• 'eig': eigenvalues, percentage of explained variance and cumulative percentage of explained variance.

• 'var': results for the variables.

• 'var$coord': coordinates of the variables on the retained dimensions.

• 'var$cor': Riemannian correlation matrix.

• 'var$cov': Riemannian covariance matrix.

• 'ind': results for the individuals.

• 'ind$similarities': similarity matrix.

• 'ind$rho': Riemannian dissimilarity matrix.

• 'ind$differences': Riemannian differences.

• 'ind$distance.matrix': Riemannian distance matrix.

• 'ind$coord': coordinates of the individuals on the retained dimensions.

Examples

model <- riem.pca(
  data = iris[, 1:4],
  scale.unit = TRUE,
  ncp = 2,
  method = "umap",
  n.neighbors = 5
)

model
round(model$eig, 4)
head(model$ind$coord)
model$var$coord

Plot Riemannian PCA Results

Description

Plots individuals or variables from a Riemannian PCA object or from manually supplied coordinates.

Usage

riem.plot(data, ...)

Arguments

Value

A plot.

Default Method for Riemannian PCA Plots

Description

Default Method for Riemannian PCA Plots

Usage

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

Arguments

Value

A plot.

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 Riemannian PCA Results

Description

Plot Riemannian PCA Results

Usage

## S3 method for class 'riem.pca'
riem.plot(data, choix = c("ind", "var"), axes = NULL, title = NULL, ...)

Arguments

Value

A plot.

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.plot3d(
  data,
  x.col,
  y.col,
  z.col,
  cluster.col = NULL,
  label.col = NULL,
  title = "",
  explained.inertia = 0,
  point.size = 5,
  alpha = 1
)

Arguments

Details

This function requires the optional package 'plotly'.

Value

A 'plotly' htmlwidget.

Examples

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

riem.plot3d(
  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

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 DBSCAN-Induced Similarities

Description

Calculates a dense matrix of similarities induced by DBSCAN clustering, local density and pairwise distances.

Usage

riem.similarities.dbscan(
  data,
  n.neighbors = 3,
  metric = "euclidean",
  sigma = NULL,
  max.neighbors = NULL,
  verbose = FALSE,
  eps = NULL,
  eps.quantile = 0.9,
  minPts = NULL,
  density.power = 1,
  between.cluster.factor = 0.05,
  noise.factor = 0.1,
  use.only.eps.neighborhood = FALSE
)

Arguments

Details

This function combines distance-based similarity, local density information and DBSCAN cluster membership to construct a similarity matrix suitable for Riemannian statistical workflows.

The similarity between observations is computed from three components:

S_{dist}(i,j) = \exp(-d_{ij} / \sigma)

where 'd_ij' is the pairwise distance between observations 'i' and 'j'.

This distance-based similarity is then multiplied by a local density factor and a cluster-membership factor. Observations in the same non-noise DBSCAN cluster receive no cluster penalization, observations in different clusters receive the factor 'between.cluster.factor', and pairs involving DBSCAN noise receive the factor 'noise.factor'.

The diagonal is set to zero to follow the same convention used by 'riem.similarities.umap()'.

Value

A dense numeric matrix of DBSCAN-induced similarities. The returned matrix has attributes '"eps"', '"minPts"', '"sigma"', '"clusters"', '"local.density"', '"density.scaled"', '"dbscan.object"', '"metric"' and '"type"'.

Examples

similarities <- riem.similarities.dbscan(
  iris[, 1:4],
  n.neighbors = 5
)
dim(similarities)
attr(similarities, "eps")
table(attr(similarities, "clusters"))

Calculate Isomap Graph Similarities

Description

Calculates a dense matrix of similarities induced by Isomap geodesic distances from a numeric dataset.

Usage

riem.similarities.isomap(
  data,
  n.neighbors = 3,
  metric = "euclidean",
  max.neighbors = NULL,
  verbose = FALSE
)

Arguments

Details

This function builds an Isomap neighborhood graph using pairwise distances and converts the resulting geodesic distance matrix into a normalized similarity matrix.

The function first computes the original pairwise distances using [stats::dist()]. Then, it attempts to construct a connected Isomap graph using [vegan::isomapdist()]. If the graph is not connected with 'n.neighbors', the number of neighbors is increased until a connected graph is obtained or 'max.neighbors' is reached.

The Isomap geodesic distance matrix 'D' is transformed into similarities as

S_{ij} = 1 - \frac{D_{ij}}{\max(D)}

.

The diagonal is set to zero to follow the same convention used by 'riem.similarities.umap()'.

Value

A dense numeric matrix of Isomap-induced similarities. The returned matrix has attributes '"k.used"', '"D.iso"', '"d.max"', '"metric"' and '"type"'.

Examples

similarities <- riem.similarities.isomap(
  iris[, 1:4],
  n.neighbors = 5
)
dim(similarities)
attr(similarities, "k.used")

Calculate UMAP Graph Similarities

Description

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

Usage

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

Arguments

Details

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

The function constructs a fuzzy similarity graph using [uwot::similarity_graph()]. The diagonal is set to zero to follow the convention used by the other similarity functions in 'riemannianStats'.

When 'sparse = FALSE', the graph is returned as a dense numeric matrix. When 'sparse = TRUE', the sparse graph returned by 'uwot' is preserved.

Value

A numeric matrix or sparse matrix of UMAP similarities. The returned object has attributes '"n.neighbors"', '"min.dist"', '"metric"' and '"type"'.

Examples

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

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

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
)

Summarize a Riemannian Linear Regression Model

Description

Summarize a Riemannian Linear Regression Model

Usage

## S3 method for class 'riem.lm'
summary(object, ...)

Arguments

Value

An object of class '"summary.riem.lm"'.