---
title: "Simple Example of Riemannian STATS: Student DataSet - ACP-UMAP"
author: "Oldemar Rodríguez Rojas & Jennifer Lobo Vásquez"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Step-by-Step Riemannian PCA with UMAP Similarities}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE,
  fig.align = "center"
)
```

# Overview

This example shows how to use the `riemannianStats` package to explore a small
student data set and reduce its dimensionality using Riemannian principal
component analysis.

The data set contains the grades of 10 students in 5 subjects: Mathematics,
Sciences, Spanish, History, and Physical Education.

The objective is not to classify students or use predefined groups, but to
explore the general structure of the data using Riemannian principal components
based on UMAP similarities.

# 1. Load the package

The first step is to load the `riemannianStats` package.

```{r load-package}
library(riemannianStats)
```

# 2. Create the student data set

The data set contains one row per student. The first column identifies the
student, while the remaining columns contain grades in five subjects.

```{r create-data}
students <- data.frame(
  Student = c(
    "Lucia", "Pedro", "Ines", "Luis", "Andres",
    "Ana", "Carlos", "Jose", "Sonia", "Maria"
  ),
  Mathematics = c(7, 7.5, 7.6, 5, 6, 7.8, 6.3, 7.9, 6, 6.8),
  Sciences = c(6.5, 9.4, 9.2, 6.5, 6, 9.6, 6.4, 9.7, 6, 7.2),
  Spanish = c(9.2, 7.3, 8, 6.5, 7.8, 7.7, 8.2, 7.5, 6.5, 8.7),
  History = c(8.6, 7, 8, 7, 8.9, 8, 9, 8, 5.5, 9),
  PhysicalEducation = c(8, 7, 7.5, 9, 7.3, 6.5, 7.2, 6, 8.7, 7)
)

students
```

# 3. Prepare the data for the analysis

The Riemannian PCA is applied only to numeric variables. Therefore, the student
names are used as row names, while only the subject grades are kept in the data
matrix used for the analysis.

```{r prepare-data}
data.analysis <- students[, c(
  "Mathematics",
  "Sciences",
  "Spanish",
  "History",
  "PhysicalEducation"
)]

student.names <- students$Student

rownames(data.analysis) <- student.names

data.analysis
```

# 4. Fit the Riemannian PCA model

The `riem.pca()` function performs the complete Riemannian PCA workflow internally. The Riemannian structure is constructed from a similarity matrix, which can be calculated using three methods:

* `"umap"` constructs similarities from a neighborhood-based structure.
* `"isomap"` uses a neighborhood graph and geodesic distances to represent the manifold structure.
* `"dbscan"` constructs similarities using the density-based structure identified by DBSCAN.

In this example, the similarity matrix is calculated using UMAP. To use ISOMAP or DBSCAN, only the value of the `method` argument needs to be changed to `"isomap"` or `"dbscan"`, respectively.

The argument `scale.unit = FALSE` indicates that the original variables are used without standardization. The model calculates five principal components through `ncp = 5`, while the first two axes are selected for visualization using `axes = c(1, 2)`.

```{r fit-riem-pca}
modelo <- riem.pca(
  data = data.analysis,
  scale.unit = FALSE,
  ncp = 5,
  axes = c(1, 2),
  n.neighbors = 3,
  min.dist = 0.1,
  metric = "euclidean",
  method = "umap"
)

modelo
```

For example, the other similarity methods can be selected as follows:

```r
# ISOMAP similarities
method = "isomap"

# DBSCAN similarities
method = "dbscan"
```

Some arguments are method-specific. In particular, `min.dist` is used by UMAP and does not affect the ISOMAP or DBSCAN calculations.


# 5. Inspect the eigenvalues

The eigenvalues summarize the amount of inertia explained by each Riemannian
principal component. The second and third columns show the percentage of
explained inertia and the cumulative percentage, respectively.

```{r eigenvalues}
round(modelo$eig, 4)
```

The inertia explained by the first two components is useful for interpreting the
principal plane.

```{r explained-inertia-two-axes}
inertia <- sum(modelo$eig[c("comp 1", "comp 2"), "percentage of variance"])

inertia
```

# 6. Inspect the UMAP similarity matrix

The similarity matrix describes the local relationships between students. Larger
values indicate greater similarity between two students according to their grade
profiles.

```{r umap-similarities}
umap.similarities <- modelo$ind$similarities

round(umap.similarities, 3)
```

# 7. Inspect the Rho matrix

The Rho matrix is the Riemannian dissimilarity matrix derived from the similarity
matrix. It is used to weight the differences between observations.

```{r rho-matrix}
rho <- modelo$ind$rho

round(rho, 3)
```

# 8. Inspect the Riemannian differences

The Riemannian differences compare each student with the others while taking the
local similarity structure into account.

```{r riemannian-differences}
riemannian.diff <- modelo$ind$differences

round(riemannian.diff, 3)
```

# 9. Inspect the Riemannian distance matrix

The Riemannian distance matrix is computed from the Riemannian differences. It
summarizes the pairwise distances between students under the Riemannian
structure.

```{r riemannian-distances}
distance.matrix <- modelo$ind$distance.matrix

round(distance.matrix, 3)
```

# 10. Inspect the Riemannian covariance matrix

The Riemannian covariance matrix summarizes the joint variability between
subjects after incorporating the Riemannian structure of the observations.

```{r riemannian-covariance}
covariance.matrix <- modelo$var$cov

round(covariance.matrix, 3)
```

# 11. Inspect the Riemannian correlation matrix

The Riemannian correlation matrix expresses the relationships between variables
on a common scale.

```{r riemannian-correlation}
correlation.matrix <- modelo$var$cor

round(correlation.matrix, 3)
```

# 12. Inspect the individual coordinates

The individual coordinates represent the students in the reduced Riemannian
principal component space.

```{r individual-coordinates}
individual.coordinates <- modelo$ind$coord

round(individual.coordinates, 3)
```

# 13. Inspect the variable coordinates

The variable coordinates are used to interpret the relationship between the
original subjects and the Riemannian principal components.

```{r variable-coordinates}
variable.coordinates <- modelo$var$coord

round(variable.coordinates, 3)
```

# 14. Plot individuals using the object interface

The easiest way to plot the individuals is to pass the full `riem.pca` object to
`riem.plot()` and set `choix = "ind"`.

```{r plot-individuals-object, fig.width=7, fig.height=5}
riem.plot(
  modelo,
  choix = "ind",
  title = "Student grades"
)
```

# 15. Plot variables using the object interface

The correlation circle is obtained by passing the full `riem.pca` object to
`riem.plot()` and setting `choix = "var"`.

```{r plot-variables-object, fig.width=7, fig.height=7}
riem.plot(
  modelo,
  choix = "var",
  title = "Student grades"
)
```

# 16. Create a Riemannian biplot using the object interface

The biplot combines the individual principal plane with the variable arrows in a
single visualization.

```{r biplot-object, fig.width=7, fig.height=7}
riem.biplot(
  modelo,
  title = "Student grades"
)
```

# 17. Plot individuals using the manual interface

The package also allows plotting by manually passing the data, coordinates and
explained inertia. This option is useful when the user has computed the
components separately.

```{r plot-individuals-manual, fig.width=7, fig.height=5}
riem.plot(
  data = modelo$data,
  choix = "ind",
  components = modelo$ind$coord,
  explained.inertia = inertia,
  title = "Riemannian PCA"
)
```

# 18. Plot variables using the manual interface

The same manual approach can be used for the correlation circle by passing the
variable coordinates directly.

```{r plot-variables-manual, fig.width=7, fig.height=7}
riem.plot(
  data = modelo$data,
  choix = "var",
  correlations = modelo$var$coord,
  explained.inertia = inertia,
  title = "Riemannian PCA"
)
```

# 19. Summary

This example shows how to use `riem.pca()` as a complete workflow for
Riemannian principal component analysis. The function stores the most important
objects inside a single result, including similarities, the Rho matrix,
Riemannian differences, distances, covariance and correlation matrices,
individual coordinates, variable coordinates, and explained inertia.

The object can then be explored directly with components such as
`modelo$eig`, `modelo$ind$coord`, and `modelo$var$coord`, or visualized with
`riem.plot()` and `riem.biplot()`.