Merge pull request #206 from lucasimi/generate-notebook-output

Generate notebook output

Author: lucasimi

.readthedocs.yml

@@ -14,6 +14,9 @@ build:
     # nodejs: "19"
     # rust: "1.64"
     # golang: "1.19"
+  apt_packages:
+    - pandoc
+
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/requirements.txt

@@ -1,2 +1,8 @@
 sphinx_rtd_theme
-nbsphinx
+nbsphinx
+jupyter
+pandoc
+jupytext
+pandas
+scikit-learn<1.6.0
+tda-mapper

docs/source/conf.py

@@ -3,35 +3,71 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+# Notebook preprocessing
+import glob
+import os
+import subprocess
+
+NOTEBOOK_DIR = os.path.join(os.path.dirname(__file__), "notebooks")
+
+
+def convert_py_to_ipynb():
+    py_files = glob.glob(os.path.join(NOTEBOOK_DIR, "*.py"))
+    for py_file in py_files:
+        ipynb_file = py_file.replace(".py", ".ipynb")
+        subprocess.run(
+            ["jupytext", "--to", "ipynb", "--output", ipynb_file, py_file], check=True
+        )
+        subprocess.run(
+            [
+                "jupyter",
+                "nbconvert",
+                "--to",
+                "notebook",
+                "--execute",
+                "--inplace",
+                ipynb_file,
+            ],
+            check=True,
+        )
+
+
+convert_py_to_ipynb()
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'tda-mapper'
-copyright = '2024, Luca Simi'
-author = 'Luca Simi'
+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.ext.viewcode', 'sphinx_rtd_theme', 'nbsphinx']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "nbsphinx",
+]
 
-templates_path = ['_templates']
+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_logo = 'logos/tda-mapper-logo-horizontal.png'
+html_theme = "sphinx_rtd_theme"
+html_logo = "logos/tda-mapper-logo-horizontal.png"
 html_theme_options = {
-    'sticky_navigation': True,
-    'vcs_pageview_mode': 'blob',
+    "sticky_navigation": True,
+    "vcs_pageview_mode": "blob",
 }
 html_context = {
-    'display_github': True,
-    'github_user': 'lucasimi',
-    'github_repo': 'tda-mapper-python',
-    'github_version': 'main',
-    'conf_py_path': '/docs/source/',
+    "display_github": True,
+    "github_user": "lucasimi",
+    "github_repo": "tda-mapper-python",
+    "github_version": "main",
+    "conf_py_path": "/docs/source/",
 }

docs/source/notebooks/circles_online.ipynb

@@ -0,0 +1,90 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.17.0
+#   kernelspec:
+#     display_name: default
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Circles dataset
+
+# %%
+import numpy as np
+
+from matplotlib import pyplot as plt
+
+from sklearn.datasets import make_circles
+from sklearn.decomposition import PCA
+from sklearn.cluster import DBSCAN
+
+from tdamapper.learn import MapperAlgorithm
+from tdamapper.cover import CubicalCover
+from tdamapper.plot import MapperPlot
+
+X, y = make_circles(                # load a labelled dataset
+    n_samples=5000,
+    noise=0.05,
+    factor=0.3,
+    random_state=42
+)
+lens = PCA(2, random_state=42).fit_transform(X)
+
+plt.scatter(lens[:, 0], lens[:, 1], c=y, cmap='jet')
+
+# %% [markdown]
+# ### Build Mapper graph
+
+# %%
+mapper_algo = MapperAlgorithm(
+    cover=CubicalCover(
+        n_intervals=10,
+        overlap_frac=0.3
+    ),
+    clustering=DBSCAN()
+)
+
+mapper_graph = mapper_algo.fit_transform(X, lens)
+
+# %% [markdown]
+# ### Plot Mapper graph with mean
+
+# %%
+mapper_plot = MapperPlot(
+    mapper_graph,
+    dim=2,
+    iterations=60,
+    seed=42
+)
+
+fig = mapper_plot.plot_plotly(
+    colors=y,                       # color according to categorical values
+    cmap='jet',                     # Jet colormap, for classes
+    agg=np.nanmean,                 # aggregate on nodes according to mean
+    width=600,
+    height=600
+)
+
+fig.show(
+    renderer='notebook_connected',
+    config={'scrollZoom': True}
+)
+
+# %%
+mapper_plot.plot_plotly_update(
+    fig,                            # update the old figure
+    colors=y,
+    cmap='viridis',                 # viridis colormap, for ranges
+    agg=np.nanstd                   # aggregate on nodes according to std
+)                  
+    
+fig.show(
+    renderer='notebook_connected',
+    config={'scrollZoom': True}
+)

docs/source/notebooks/circles_online.py

@@ -0,0 +1,90 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.17.0
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Digits dataset
+
+# %%
+import numpy as np
+
+from sklearn.datasets import load_digits
+from sklearn.cluster import AgglomerativeClustering
+from sklearn.decomposition import PCA
+
+from tdamapper.learn import MapperAlgorithm
+from tdamapper.cover import CubicalCover
+from tdamapper.clustering import FailSafeClustering
+from tdamapper.plot import MapperPlot
+
+
+X, y = load_digits(return_X_y=True)                 # We load a labelled dataset
+lens = PCA(2, random_state=42).fit_transform(X)     # We compute the lens values
+
+# %% [markdown]
+# ### Build Mapper graph
+
+# %%
+mapper_algo = MapperAlgorithm(
+    cover=CubicalCover(
+        n_intervals=10,
+        overlap_frac=0.65
+    ),
+    clustering=AgglomerativeClustering(10),
+    verbose=False
+)
+
+mapper_graph = mapper_algo.fit_transform(X, lens)
+
+# %% [markdown]
+# ### Plot Mapper graph with mean
+
+# %%
+mapper_plot = MapperPlot(
+    mapper_graph,
+    dim=2,
+    iterations=400,
+    seed=42
+)
+
+fig = mapper_plot.plot_plotly(
+    colors=y,                        # We color according to digit values
+    cmap='jet',                      # Jet colormap, used for classes
+    agg=np.nanmean,                  # We aggregate on graph nodes according to mean
+    title='digit (mean)',
+    width=600,
+    height=600
+)
+
+fig.show(
+    renderer='notebook_connected',
+    config={'scrollZoom': True}
+)
+
+# %% [markdown]
+# ### Plot Mapper graph with standard deviation
+
+# %%
+fig = mapper_plot.plot_plotly(
+    colors=y,                        
+    cmap='viridis',                  # Viridis colormap, used for ranges
+    agg=np.nanstd,                   # We aggregate on graph nodes according to std
+    title='digit (std)',
+    width=600,
+    height=600
+)
+
+fig.show(
+    renderer='notebook_connected',
+    config={'scrollZoom': True}
+)