Improved docs. Versions fixed

Author: lucasimi

app/requirements.txt

@@ -1,7 +1,7 @@
 streamlit>=1.40.0,<2.0.0
 numpy>=1.25.2,<2.0.0
 scikit-learn>=1.5.0,<1.6.0
-umap-learn>=0.5.7,>0.6.0
+umap-learn>=0.5.7,<0.6.0
 pandas>=2.1.0,<3.0.0
 tda-mapper>=0.9.0,<0.10.0
 plotly>=6.0.0,<7.0.0

docs/source/examples.rst

@@ -2,11 +2,8 @@ Examples
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   notebooks/circles_online
-   notebooks/digits_online
-
-.. |Dataset| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png
-.. |Mapper graph (average)| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png
-.. |Mapper graph (standard deviation)| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_std.png
+   notebooks/circles
+   notebooks/digits
+   

docs/source/notebooks/circles.py

@@ -0,0 +1,127 @@
+# ---
+# 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]
+# # Example 1: Exploring Shape
+# In this notebook, we use the **Mapper algorithm** to analyze a toy dataset
+# composed of two concentric circles. This simple example is a classic case in
+# topology and machine learning, and it's perfect for gaining an intuitive
+# understanding of how Mapper captures shape. Although this dataset is
+# synthetic and well understood, it's ideal for visualizing how Mapper detects
+# underlying **topological structures**—in this case, two distinct loops. The
+# resulting Mapper graph should ideally reveal two connected components,
+# corresponding to the two circular regions.
+
+
+# %% [markdown]
+# ### Mapper pipeline
+
+# %% [markdown]
+# We generate a synthetic dataset using `make_circles`, which creates two
+# concentric circles in 2D space. To prepare the data for Mapper, we apply
+# **Principal Component Analysis (PCA)** to extract the top two components.
+# These will serve as our **lens function**, which helps Mapper cover the data
+# in a meaningful way. Even though the dataset is already 2D, PCA is still a
+# useful and consistent choice for this example, especially when scaling up to
+# higher-dimensional problems.
+
+
+# %%
+import numpy as np
+from matplotlib import pyplot as plt
+from sklearn.cluster import DBSCAN
+from sklearn.datasets import make_circles
+from sklearn.decomposition import PCA
+
+from tdamapper.cover import CubicalCover
+from tdamapper.learn import MapperAlgorithm
+from tdamapper.plot import MapperPlot
+
+X, labels = make_circles(n_samples=5000, noise=0.05, factor=0.3, random_state=42)
+
+fig = plt.figure(figsize=(5, 5), dpi=100)
+plt.scatter(X[:, 0], X[:, 1], c=labels, s=0.25, cmap="jet")
+plt.axis("off")
+plt.show()
+# fig.savefig("circles_dataset.png", dpi=100)
+
+y = PCA(2, random_state=42).fit_transform(X)
+
+# %% [markdown]
+# We now build the Mapper graph using the PCA output as the lens. Mapper
+# requires two key components:
+#
+# - A **cover** algorithm that defines how the data is grouped together along
+#   the lens
+# - A **clustering algorithm** that splits each set of the open cover.
+#
+# In this example, we use a **cubical cover** with 10 intervals and 30%
+# overlap, and we apply **DBSCAN** for clustering, which is well-suited for
+# identifying arbitrary shapes. Choosing these parameters often involves some
+# trial and error based on the dataset and the desired resolution of the Mapper
+# graph.
+
+# %%
+mapper = MapperAlgorithm(
+    cover=CubicalCover(n_intervals=10, overlap_frac=0.3), clustering=DBSCAN()
+)
+graph = mapper.fit_transform(X, y)
+
+# %% [markdown]
+# ### Visualization
+
+# %% [markdown]
+# We visualize the Mapper graph by coloring each node according to the **mean**
+# class label (0 or 1). Since the dataset contains two classes—one for each
+# circle—this coloring helps us verify whether the graph structure aligns with
+# the true geometry of the data. Ideally, nodes corresponding to the inner and
+# outer circles will show clear separation in color, revealing two distinct
+# connected components in the graph.
+
+# %%
+plot = MapperPlot(graph, dim=2, iterations=60, seed=42)
+
+fig = plot.plot_plotly(colors=labels, cmap="jet", agg=np.nanmean, width=600, height=600)
+
+fig.show(config={"scrollZoom": True})
+# fig.write_image("circles_mean.png", width=500, height=500)
+
+# %% [markdown]
+# To explore areas where the two classes might overlap or be hard to
+# distinguish, we color each node by the **standard deviation** of class
+# labels. A low standard deviation (close to 0) indicates that all samples in a
+# node belong to the same class, while a higher value suggests label ambiguity
+# within the node. This helps highlight transitional regions in the dataset
+# where class boundaries may not be as sharp—useful when analyzing real-world
+# data where such ambiguity is common.
+
+# %%
+plot.plot_plotly_update(
+    fig,
+    colors=labels,
+    cmap="viridis",
+    agg=np.nanstd,
+)
+
+fig.show(config={"scrollZoom": True})
+# fig.write_image("circles_std.png", width=500, height=500)
+
+# %% [markdown]
+# ### Conclusions
+# This simple example demonstrates how the Mapper algorithm can uncover
+# meaningful topological structures, even in a basic synthetic dataset. By
+# combining dimensionality reduction (PCA), a thoughtful cover strategy, and
+# clustering, Mapper captures the two-loop shape of concentric circles and
+# visualizes label consistency and ambiguity across the dataset. This forms a
+# solid foundation for applying Mapper to more complex, real-world datasets.