Feature/add docs

.gitignore

@@ -4,6 +4,7 @@
 **/*.egg-info
 **/.ipynb_checkpoints
 **/*.log
+**/docs/build
 
 .coverage
 .vscode

.readthedocs.yml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

README.md

@@ -1,4 +1,4 @@
-# tda-mapper-python 
+# tda-mapper
 
 ![test](https://github.com/lucasimi/tda-mapper-python/actions/workflows/test.yml/badge.svg) [![codecov](https://codecov.io/github/lucasimi/tda-mapper-python/graph/badge.svg?token=FWSD8JUG6R)](https://codecov.io/github/lucasimi/tda-mapper-python)
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'tda-mapper'
+copyright = '2024, Luca Simi'
+author = 'Luca Simi'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,20 @@
+.. tda-mapper documentation master file, created by
+   sphinx-quickstart on Fri Jan 26 21:56:08 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to tda-mapper's documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/modules.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 4
+
+   tdamapper

docs/source/tdamapper.rst

@@ -0,0 +1,31 @@
+tdamapper.core Mapper Algorithm
+-------------------------------
+
+.. automodule:: tdamapper.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.cover Cover Algorithms
+--------------------------------
+
+.. automodule:: tdamapper.cover
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.clustering Clustering Algorithms
+------------------------------------------
+
+.. automodule:: tdamapper.clustering
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.plot Mapper Plot
+--------------------------
+
+.. automodule:: tdamapper.plot
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/tdamapper.utils.rst

@@ -0,0 +1,53 @@
+tdamapper.utils package
+=======================
+
+Submodules
+----------
+
+tdamapper.utils.heap module
+---------------------------
+
+.. automodule:: tdamapper.utils.heap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.utils.quickselect module
+----------------------------------
+
+.. automodule:: tdamapper.utils.quickselect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.utils.unionfind module
+--------------------------------
+
+.. automodule:: tdamapper.utils.unionfind
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.utils.vptree module
+-----------------------------
+
+.. automodule:: tdamapper.utils.vptree
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+tdamapper.utils.vptree\_flat module
+-----------------------------------
+
+.. automodule:: tdamapper.utils.vptree_flat
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: tdamapper.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/tdamapper/core.py

@@ -9,34 +9,49 @@
 _ID_NEIGHS = 1
 
 
-class ProximityNet:
-
-    def __init__(self, cover):
-        self.__cover = cover
+def proximity_net(X, proximity):
+    '''
+    Compute the proximity-net for a given open cover.
 
-    def proximity_net(self, X):
-        covered_ids = set()
-        proximity = self.__cover.proximity()
-        proximity.fit(X)
-        for i, xi in enumerate(X):
-            if i not in covered_ids:
-                neigh_ids = proximity.search(xi)
-                covered_ids.update(neigh_ids)
-                if neigh_ids:
-                    yield neigh_ids
+    :param X: A dataset
+    :type X: numpy.ndarray or list-like
+    :param cover: A cover algorithm
+    :type cover: A class from tdamapper.cover
+    '''
+    covered_ids = set()
+    proximity.fit(X)
+    for i, xi in enumerate(X):
+        if i not in covered_ids:
+            neigh_ids = proximity.search(xi)
+            covered_ids.update(neigh_ids)
+            if neigh_ids:
+                yield neigh_ids
 
 
 def build_labels_par(X, y, cover, clustering, n_jobs):
     '''
-    Takes a dataset, returns a list of lists, where the list at position i
-    contains the cluster ids to which the item at position i belongs to.
-    * Each list in the output is a sorted list of ints with no duplicate.
+    Computes the local cluster labels for each element of the dataset and stores them in a list.
+    Each item in the returned list is a sorted list of ints with no duplicate.
+    The list at position i contains the cluster ids to which the point at position i belongs to. 
+
+    :param X: A dataset
+    :type X: numpy.ndarray or list-like
+    :param y: lens values
+    :type y: numpy.ndarray or list-like
+    :param cover: A cover algorithm
+    :type cover: A class from tdamapper.cover
+    :param clustering: A clustering algorithm
+    :type clustering: A class from tdamapper.clustering or a class from sklearn.cluster
+    :param n_jobs: The number of parallel jobs for clustering
+    :type n_jobs: int
+    :return: The labels list
+    :rtype: list[list[int]]
     '''
     def _lbls(x_ids):
         x_data = [X[j] for j in x_ids]
         x_lbls = clustering.fit(x_data).labels_
         return x_ids, x_lbls
-    net = ProximityNet(cover).proximity_net(y)
+    net = proximity_net(y, cover.proximity())
     par = Parallel(n_jobs=n_jobs)(delayed(_lbls)(ids) for ids in net)
     max_lbl = 0
     lbls = [[] for _ in X]
@@ -57,6 +72,9 @@ def build_adjaciency(labels):
     mapped to a couple. Inside each couple the first entry is the list 
     of positions where the item is present, the second entry is the list
     of items which appear in any of the lists where the key is present.
+
+    :param labels: A list of lists 
+    :type labels: list[list[int]]
     '''
     adj = {}
     for n, clusters in enumerate(labels):
@@ -81,6 +99,16 @@ def build_adjaciency(labels):
 
 
 def build_graph(X, y, cover, clustering, n_jobs=1):
+    ''' 
+    Computes the Mapper Graph
+
+    :param X: A dataset
+    :type X: numpy.ndarray or list-like
+    :param y: Lens values
+    :type y: numpy.ndarray or list-like
+    :return: The Mapper Graph
+    :rtype: networkx.Graph
+    '''
     labels = build_labels_par(X, y, cover, clustering, n_jobs)
     adjaciency = build_adjaciency(labels)
     graph = nx.Graph()
@@ -103,6 +131,9 @@ def build_connected_components(graph):
     from the dataset, returns a list of integers, where position i is the id
     of the connected component of the graph where the element at position i 
     from the dataset lies.
+
+    :param graph: Any graph
+    :type graph: networkx.Graph
     '''
     cc_id = 1
     item_cc = {}
@@ -125,6 +156,14 @@ def compute_local_interpolation(y, graph, agg):
 
 
 class MapperAlgorithm:
+    ''' 
+    Main class for performing the Mapper Algorithm.
+
+    :param cover: A cover algorithm
+    :type cover: A class from tdamapper.cover
+    :param clustering: A clustering algorithm
+    :type clustering: A class from tdamapper.clustering or a class from sklearn.cluster
+    '''
 
     def __init__(self, cover, clustering, n_jobs=1):
         self.__cover = cover
@@ -133,8 +172,27 @@ def __init__(self, cover, clustering, n_jobs=1):
         self.graph_ = None
 
     def fit(self, X, y=None):
+        ''' 
+        Computes the Mapper Graph
+
+        :param X: A dataset
+        :type X: numpy.ndarray or list-like
+        :param y: Lens values
+        :type y: numpy.ndarray or list-like
+        :return: self
+        '''
         self.graph_ = self.fit_transform(X, y)
         return self
 
     def fit_transform(self, X, y):
+        ''' 
+        Computes the Mapper Graph
+
+        :param X: A dataset
+        :type X: numpy.ndarray or list-like
+        :param y: Lens values
+        :type y: numpy.ndarray or list-like
+        :return: The Mapper Graph
+        :rtype: networkx.Graph
+        '''
         return build_graph(X, y, self.__cover, self.__clustering, self.__n_jobs)