riemannian-stats 0.1.1

Riemannian STATS is a package for applying Principal Component Analysis on Riemannian manifolds using UMAP-derived local geometry, enabling powerful dimensionality reduction and visualization for any type of data.

Riemannian STATS: Statistical Analysis on Riemannian Manifolds

---

RiemannianStats is an open-source package that implements a novel principal component analysis methodology adapted for data on Riemannian manifolds, using UMAP as a core tool to construct the underlying geometric structure. This tool enables advanced statistical techniques to be applied to any type of dataset, honoring its local geometry, without requiring the data to originate from traditionally geometric domains like medical imaging or shape analysis.

Instead of assuming data resides in Euclidean space, RiemannianStats transforms any data table into a Riemannian manifold by leveraging the local connectivity extracted from a UMAP-generated k-nearest neighbor graph. On top of this structure, the package computes Riemannian principal components, covariance and correlation matrices, and even provides 2D and 3D visualizations that faithfully capture the dataset’s topology.

With Riemannian STATS, you can:

• Incorporate the local geometry of your data for meaningful dimensionality reduction.
• Generate visual representations that better reflect the true structure of your data.
• Use a unified framework that generalizes classical statistical analysis to complex geometric contexts.
• Apply these techniques to both synthetic and real high-dimensional datasets.

This package is ideal for researchers, data scientists, and developers seeking to move beyond the traditional assumptions of classical statistics, applying models that respect the intrinsic structure of data.

🌐 Package Website

You can explore the Riemannian STATS package documentation , its features, and interactive examples at: 🔗 https://riemannianstats.web.app

---

Features and Modules

Functionality	Module	Documentation
Data preprocessing	data_processing.py	🔗 data_processing
Riemannian analysis	riemannian_analysis.py	🔗 riemannian_analysis
Visualizations (2D/3D)	visualization.py	🔗 visualization
Utilities	utilities.py	🔗 utilities

---

📚 Examples of Use

The examples/ directory contains three complete use cases applying Riemannian STATS to different datasets:

Dataset	Description	Script	Results
Iris	Applies Riemannian PCA to 150 flowers from 3 species using 4 morphological variables (sepal/petal length and width). Visualizes species in component space.	🧾 example1.py	📊 View Output
Data10D_250	Synthetic dataset with 250 points in 10 dimensions and labeled clusters. Computes UMAP similarities, rho matrix, R-PCA, and correlation analysis.	🧾 example2.py	📊 View Output
Olivetti Faces	400 grayscale face images (64×64 pixels, 4096D) from 40 individuals. Projects them into Riemannian component space for identity separation and visualization.	🧾 example3.py	📊 View Output

📖 For full walkthroughs with inputs, outputs, and visualizations: 📊 Examples Overview

---

Importing the Package

riemannian_stats supports both PascalCase and lowercase alias imports for flexibility:

# Standard
from riemannian_stats import RiemannianAnalysis, DataProcessing, Visualization, Utilities

# Aliased (optional)
from riemannian_stats import riemannian_analysis, data_processing, visualization, utilities

💡 Both styles provide access to the same functionality—choose the one that best fits your coding preferences.

---

Installation

Ensure you have Python ≥ 3.8 installed, then run:

pip install riemannian_stats

Alternatively, to install from the source code, clone the repository and execute:

git clone https://github.com/OldemarRodriguez/riemannian_stats.git
cd riemannian_stats
pip install .

This project follows PEP 621 and uses pyproject.toml as the primary configuration file.

Main Dependencies:

• matplotlib (>=3.7.5, <3.11)
• pandas (>=2.0.3, <2.3)
• numpy (>=1.24.4, <3.0)
• scikit-learn (>=1.3.2, <1.7)
• umap-learn (>=0.5.7, <0.6)

These dependencies are defined in the pyproject.toml and in requirements.txt .

---

License

Distributed under the BSD-3-Clause License. See the LICENSE.txt for more details.

---

Authors & Contributors

• Oldemar Rodríguez Rojas – Developed the mathematical functions and conducted the research.
• Jennifer Lobo Vásquez – Led the overall development and integration of the package.

---

Support & Contributions

If you encounter any issues or have suggestions for improvements, please open an issue on the repository or submit a pull request. Your feedback is invaluable to enhancing the package.

To learn how to contribute effectively, please refer to the Contributing.md file, where you’ll find guidelines and best practices to get involved.

---

References

• Matplotlib Documentation
  Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python.
  PyPI: matplotlib · PyPI

• Pandas Documentation
  Pandas provides high-performance, easy-to-use data structures and data analysis tools for Python.
  PyPI: pandas · PyPI

• NumPy Documentation
  NumPy is the fundamental package for numerical computation in Python.
  PyPI: numpy · PyPI

• Scikit-learn Documentation
  Scikit-learn is a machine learning library for Python, providing tools for classification, regression, clustering, and dimensionality reduction.
  PyPI: scikit-learn · PyPI

• UMAP-learn Documentation
  UMAP (Uniform Manifold Approximation and Projection) is a dimension reduction technique for visualization and general non-linear dimension reduction.
  PyPI: umap-learn · PyPI

• Setuptools Documentation
  Setuptools is a package development and distribution tool used to package Python projects and manage dependencies.
  PyPI: setuptools · PyPI