---
title: "Simple Example of Riemannian STATS: Student Data Set"
author: "Oldemar Rodríguez Rojas & Jennifer Lobo Vásquez"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Student example}
  %\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.

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

The objective of this example is not to classify students or use known groups,
but to explore the general structure of the data using Riemannian principal
components.


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

# 1. Create the data set

The first column identifies each student, and the remaining columns contain their
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
```

# 2. Prepare the data for the analysis

The Riemannian analysis is applied only to numeric variables. Therefore, the
`Student` column is used as the row names, while only the subject grades are kept
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
```

# 3. Compute UMAP similarities

First, a local similarity matrix between students is computed. This matrix
summarizes which students are close to each other according to their grade
patterns.

```{r calculate-similarities}
n.neighbors <- 3

umap.similarities <- riem.similarities.umap(
  data = data.analysis,
  n.neighbors = n.neighbors,
  min.dist = 0.1,
  metric = "euclidean"
)

round(umap.similarities, 3)
```

# 4. Compute the Rho matrix

The Rho matrix is obtained as `1 - umap.similarities`. This matrix is used to
weight the differences between students.

```{r calculate-rho}
rho <- riem.rho(umap.similarities)

round(rho, 3)
```

# 5. Compute Riemannian differences and distances

Riemannian differences compare each student with the others, weighting those
differences by the local structure of the data.

```{r calculate-differences}
riemannian.diff <- riem.diff(data = data.analysis, rho = rho)

dim(riemannian.diff)
```

A Riemannian distance matrix is then computed from those differences.

```{r calculate-distances}
distance.matrix <- riem.dist(riemannian.diff)

round(distance.matrix, 3)
```

# 6. Compute Riemannian covariance and correlation

The Riemannian covariance matrix summarizes the joint variability of the
subjects while considering Riemannian centering.

```{r covariance}
covariance.matrix <- riem.cov(
  data = data.analysis,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

round(covariance.matrix, 3)
```

The Riemannian correlation matrix makes it possible to compare the relationship
between subjects on a common scale.

```{r correlation}
correlation.matrix <- riem.cor(
  data = data.analysis,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

round(correlation.matrix, 3)
```

# 7. Compute Riemannian principal components

Riemannian principal components make it possible to represent students in a
lower-dimensional space.

```{r components}
components <- riem.ind.coord(
  data = data.analysis,
  correlation.matrix = correlation.matrix,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

round(components, 3)
```

# 8. Compute explained inertia

Explained inertia indicates the proportion of total variability represented by
the selected components.

```{r inertia}
inertia <- riem.inertia(
  correlation.matrix = correlation.matrix,
  component1 = 1,
  component2 = 2
) * 100

inertia
```

# 9. Interpret the subjects in the reduced space

The correlations between the subjects and the components help interpret which
subjects are most associated with each axis of the principal plane.

```{r loadings}
loadings <- riem.var.coord(
  data = data.analysis,
  components = components,
  rho = rho,
  umap.distance.matrix = distance.matrix
)

round(loadings, 3)
```

# 10. Visualize the principal plane

The principal plane represents the students using the first two Riemannian
components. In this example, no clusters are used because the objective is to
explore the structure of the data without predefined groups.

```{r principal-plane, fig.width=7, fig.height=5}
riem.plot(
  data = data.analysis,
  choix = "ind",
  components = components,
  explained.inertia = inertia,
  title = "Student grades"
)
```

# 11. Visualize the correlation circle

The correlation circle helps interpret how the subjects are related to the first
two Riemannian components.

```{r correlation-circle, fig.width=7, fig.height=7}
riem.plot(
  data = data.analysis,
  choix = "var",
  correlations = loadings,
  explained.inertia = inertia,
  title = "Student grades"
)
```

# 12. Visualize the biplot

The biplot combines the principal plane of the students with the variable arrows,
allowing the structure of the observations and the interpretation of the subjects
to be explored in the same figure.

```{r biplot, fig.width=7, fig.height=7}
riem.biplot(
  data = data.analysis,
  components = components,
  correlations = loadings,
  explained.inertia = inertia,
  title = "Student grades"
)
```

This example shows how to apply `riemannianStats` to a small and simple data set.
The workflow computes Riemannian similarities, distances, correlations, and
principal components in order to explore the structure of the grades and reduce
the dimensionality of the data.