notebooks/00_foundations__introduction_to_geomstats.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4c913006",
   "metadata": {},
   "source": [
    "$\\textbf{Lead Author: Adele Myers}$\n",
    "\n",
    "Inspired by: Guigui, Miolane, Pennec, 2022. Introduction to Riemannian Geometry and Geometric Statistics: from basic theory to implementation with Geomstats."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90376931",
   "metadata": {},
   "source": [
    "Dear Learner,\n",
    "\n",
    "Welcome. This is a set of notebooks designed to teach you how to use (and hopefully understand) a software package called Geomstats. Geomstats is an open source code that uses concepts from Differential Geometry and Riemannian Geometry to analyze data that lie on manifolds (what it means for \"data to lie on a manifold\" will be explained in further detail in the next section). Before Geomstats and software packages like it were developed, analyzing data on manifolds could be a difficult task for people without prior knowledge of differential geometry. The Geomstats package aims to make this type of data analysis more accessible to people who do not have prior knowledge of Riemannian geometry. These instructional notebooks work towards Geomstats' goal to foster accessibility."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c97afd26",
   "metadata": {},
   "source": [
    "For those interested, the following paper <a href=\"https://www.jmlr.org/papers/volume21/19-027/19-027.pdf\"> [Miolane et al 2020.]</a> compares Geomstats to other software packages like it (on page 5). "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6025ab5a",
   "metadata": {},
   "source": [
    "# What is the motivation for analyzing data on manifolds?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "991d1f57",
   "metadata": {},
   "source": [
    "Many data sets lie on a manifold. The definition of manifold will be introduced later, but for now we can think of a manifold as being something like a surface, such as the surface (2-dimensional sphere) in the figure below. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e873b072",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_sphere_manifold.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cdd76be",
   "metadata": {},
   "source": [
    "Analyzing data that lie on manifolds is often possible without Riemannain Geometry, but choosing to analyze data on manifolds is advantageous for three reasons:\n",
    "\n",
    "1. Analyzing data on the manifold it lies on allows you to reduce the degrees of freedom of the system, which makes  computations less complicated and more intuitive and interpretable.\n",
    "2. Knowing the manifold that a data set belongs to will give you a better understanding of the data's evolution.\n",
    "3. Knowing the manifold a data set lives in give you better predictive power and will help you extract the \"signal\" from a noisy data set or a data set with very few datapoints."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d84c555",
   "metadata": {},
   "source": [
    "### 1) Analyzing data on a manifold reduces the degrees of freedom of the system, making computations less complicated."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "631532a8",
   "metadata": {},
   "source": [
    "The number of $\\textbf{Degrees of Freedom}$ a system has is equivalent to the number of variables needed to describe the system completely. For example, an object moving freely in three dimensions will require three variables to describe it completely $(x,y,z)$; or $(\\phi,\\theta, r)$ in spherical coordinates- see Figure (a), below. However, if you know that the point lies on the surface of a sphere of known radius, then you would only need to use two variables, $(\\theta,\\phi)$, to specify its position- see Figure (b), below.\n",
    "\n",
    "Knowing that the point lies on the surface of a manifold (a sphere) allows us to use fewer variables to record its location, which is computationally more efficient in terms of memory requirements, and less mentally taxing (if you are solving a problem on paper)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa1eca22",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_degrees_of_freedom.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83cb9d11",
   "metadata": {},
   "source": [
    "Reducing the number of variables is one of the major motivations behind using manifolds to analyze data. Of course, it is sometimes possible to analyze data without manifolds and Riemannian Geometry, but this will be more complicated and computationally intensive."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc917a23",
   "metadata": {},
   "source": [
    "### 2) Knowing the manifold that a data set belongs to may give you a deeper understanding of your data's evolution or \"why your data looks/evolves the way it does\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3ee9db9",
   "metadata": {},
   "source": [
    "Objects travelling along a manifold often follow geodesics on that manifold. When the manifold is equipped with a so-called \"Riemannian metric\" (which will be introduced in a later notebook), we can define geodesics on the manifold. The geodesic is the path of shortest distance that a particle can travel in the space that it is in. For example, geodesics in 2D and 3D space are straight lines are the shortest way to get from one point to another. The figure below shows paths between two points in cartesian space. One path ($\\gamma$) is a geodesic in cartesian coordinates, and the other path ($\\gamma^{'}$) is not a geodesic. Figure (a) shows this in 2D, and Figure (b) shows this in 3D."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4fa175e",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_cartesian_geodesic.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4f89c6f",
   "metadata": {},
   "source": [
    "However, when an object lies in a higher dimensional curved space, its geodesic will not follow a straight line. For example, if an object is constrained to move along the surface of a sphere, the shortest path between points is not a straight line, but rather, a curve. A straight line in 3D space would not lie on the surface of a sphere, so it cannot be the shortest path along the sphere. The figure below shows $\\gamma$, which is a geodesic on the sphere, along with $\\gamma^{'}$, which is not a geodesic on the sphere."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c95315a0",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_sphere_geodesic.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7bc7d4bc",
   "metadata": {},
   "source": [
    "If you did not know that the object was moving along the surface of the sphere, you would wonder why it is taking such an \"irratic\" path instead of just going straight. The motion of the particles in your system might seem random because you do not understand the space they are moving in. However, if you learn more about the space they are moving in (the surface of a sphere), you would realize that the particles are following very reasonable and predictable paths along geodesics, and this would give you $\\textit{not only}$ a better understanding of how particles have moved in the past but $\\textit{also}$ predictive power to determine how particles will move in the future."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92d789e5",
   "metadata": {},
   "source": [
    "### 3) Knowing the manifold a data set lives in will help you give you better predictive power and extract the \"signal\" from a noisy data set or a data set with very few datapoints."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "393b28f9",
   "metadata": {},
   "source": [
    "Let's begin with a simpler example in cartesian coordinates. Let's say that you are measuring the position of a car moving at constant velocity, but you dropped your position-measuring-device after only one measurement, and your data looks like this:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c57e3147",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_random_point.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9adc331",
   "metadata": {},
   "source": [
    "How can you get any information from this? It would be very difficult to get information from this if you don't have an exact model for what the data $\\textit{should}$ look like. Luckily, it is well known that objects moving with constant velocity $v$ can be modelled by the equation $x_f = x_i + v\\Delta t$, so even though you do not have many data points, you will still be able to accurately predict your car's future position. However, if you did not know that your data should follow a straight line such as in Figure (c) or Figure (d), or you did not know the car's velocity v such as in Figure (b), then you might try to fit the data using incorrect models, and your (incorrect) model would not be able to accurately predict the car's future position."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa17215d",
   "metadata": {},
   "source": [
    "In the following figure, the green point in each graph shows the single measured point (the car's only measured position), and the purple points show future points (the car's future positions). Note that we are only able to accurately predict future points with a correct model."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e892a4e9",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_point_fits.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37a093ac",
   "metadata": {},
   "source": [
    "Similarly, knowing the exact manifold your data lies on can help you analyze your current data points and predict future data. For example, let's say that your data lives on a 2-dimensional sphere, as shown below."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe60fa8c",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_points_on_manifold.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e06ce4aa",
   "metadata": {},
   "source": [
    "If you did not know that your data live on the surface of a sphere or you did not, then you might try to fit your data with a line (such as in Figure (b) below) instead of using Geomstats to analyze your data, which appears to follow a geodesic curve on a sphere (shown in Figure (a) below)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d55415a0",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_modelling_points_on_manifold.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee8441a1",
   "metadata": {},
   "source": [
    "$\\textbf{A note about Geomstat's current capabilities:}$\n",
    "\n",
    "Our current version of Geomstats cannot tell you $\\textit{which}$ manifold your data lives on, and it also cannot perform \"manifold fitting\" (adjusting the general parameters of a manifold to fit your data set). For example, Geomstats cannot tell you if your data lives on the surface of a sphere, and if you $\\textit{know}$ that your data falls on the surface of a sphere, Geomstats cannot tell you what the radius of that sphere is. \n",
    "\n",
    "However, if you $\\textit{know}$ the exact manifold that your data lives on (e.g. you know that your data lives on a sphere of radius R=3), then you can $\\textit{use}$ Geomstats to unlock the predictive power that differential geometry can provide you."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b75cda3f",
   "metadata": {},
   "source": [
    "# What will you learn in these tutorials?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cd75c7e",
   "metadata": {},
   "source": [
    "Geomstats is designed to be intuitive and user friendly, but having some knowledge about Riemannian Geometry will put you in a good position to understand how to use Geomstats most effectively. Therefore, in the next three notebooks, we will give you an overview of three of the most important parent classes in Geomstats, along with a description of the matematical concepts implemented in each class."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb00ea16",
   "metadata": {},
   "source": [
    "We will cover the parent classes (\"parent class\" in the sense of <a href=\"https://www.educative.io/blog/object-oriented-programming\"> object oriented programming</a>) :\n",
    "\n",
    "\n",
    "1. Manifold\n",
    "2. Connection (and RiemannianMetric)\n",
    "    \n",
    "One instructional notebook will be dedicated to the manifold class, and one notebook will be dedicated to the Connection and RiemannianMetric classes. Connection and RiemannianMetric are grouped into one notebook because RiemannianMetric inherits from Connection.\n",
    "\n",
    "In each of these notebooks, you should expect to gain an understanding of\n",
    "\n",
    "1. the structure/hierarchy of the Geomstats code\n",
    "2. how to perform calculations on manifolds\n",
    "3. the mathematical theory behind the Geomstats code"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c5c22f9",
   "metadata": {},
   "source": [
    " # Beginning to build a hierarchical map"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfe827e1",
   "metadata": {},
   "source": [
    "Now that we know about these three parent classes, we will begin to draw a hierarchical map of geomstats, which we will build out as we learn more about each parent class."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2545baa",
   "metadata": {},
   "source": [
    "<img src=\"figures/intro_hierarchal_map.png\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e96d68b9",
   "metadata": {},
   "source": [
    "In the next notebook, we will discuss the Manifold class."
   ]
  }
 ],
 "metadata": {
  "backends": [
   "numpy",
   "autograd"
  ],
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}