updated doc for new API

Author: quentinhaenn

docs/source/usage.rst

@@ -1,7 +1,20 @@
 Usage
 =====
 
-Here's a basic example of how to use Radius Clustering:
+This page provides a quick guide on how to use the `radius_clustering` package for clustering tasks. The package provides a simple interface for performing radius-based clustering on datasets based on the Minimum Dominating Set (MDS) algorithm.
+
+This page is divided into three main sections:
+1. **Basic Usage**: A quick example of how to use the `RadiusClustering` class and perform clustering with several parameters.
+2. **Custom Dissimilarity Function**: How to use a custom dissimilarity function with the `RadiusClustering` class.
+3. **Custom MDS Solver**: How to implement a custom MDS solver for more advanced clustering tasks, eventually with less guarantees on the results.
+
+
+Basic Usage
+-----------------
+
+The `RadiusClustering` class provides a straightforward way to perform clustering based on a specified radius. You can choose between an approximate or exact method for clustering, depending on your needs.
+
+Here's a basic example of how to use Radius Clustering with the `RadiusClustering` class, using the approximate method:
 
 .. code-block:: python
 
@@ -22,4 +35,93 @@ Here's a basic example of how to use Radius Clustering:
    # Get cluster labels
    labels = rad.labels_
 
-   print(labels)
+   print(labels)
+
+Similarly, you can use the exact method by changing the `manner` parameter to `"exact"`:
+.. code-block:: python
+   # [...] Exact same code as above
+   rad = RadiusClustering(manner="exact", radius=0.5) #change this parameter
+   # [...] Exact same code as above
+
+Custom Dissimilarity Function
+-----------------------------
+
+The main reason behind the `radius_clustering` package is that users eventually needs to use a dissimilarity function that is not a metric (or distance) function. Plus, sometimes context requires a domain-specific dissimilarity function that is not provided by default, and needs to be implemented by the user.
+
+To use a custom dissimilarity function, you can pass it as a parameter to the `RadiusClustering` class. Here's an example of how to do this:
+.. code-block:: python
+
+   from radius_clustering import RadiusClustering
+   import numpy as np
+
+   # Generate random data
+   X = np.random.rand(100, 2)
+
+   # Define a custom dissimilarity function
+   def dummy_dissimilarity(x, y):
+       return np.linalg.norm(x - y) + 0.1  # Example: add a constant to the distance
+
+   # Create an instance of MdsClustering with the custom dissimilarity function
+   rad = RadiusClustering(manner="approx", radius=0.5, metric=dummy_dissimilarity)
+
+   # Fit the model to the data
+   rad.fit(X)
+
+   # Get cluster labels
+   labels = rad.labels_
+
+   print(labels)
+
+
+.. note::
+   The custom dissimilarity function will be passed to scikit-learn's `pairwise_distances` function, so it should be compatible with the expected input format and return type. See the scikit-learn documentation for more details on how to implement custom metrics.
+
+Custom MDS Solver
+-----------------
+
+The two default solvers provided by the actual implementation of the `radius_clustering` package are focused on exactness (or proximity to exactness) of the results of a NP-hard problem. So, they may not be suitable for all use cases, especially when performance is a concern.
+If you have your own implementation of a Minimum Dominating Set (MDS) solver, you can use it with the `RadiusClustering` class ny using the :py:func:'RadiusClustering.set_solver' method. It will check that the solver is compatible with the expected input format and return type, and will use it to perform clustering.
+
+Here's an example of how to implement a custom MDS solver and use it with the `RadiusClustering` class, using NetworkX implementation of the dominating set problem : 
+
+.. code-block:: python
+
+   from radius_clustering import RadiusClustering
+   import time
+   import numpy as np
+   import networkx as nx
+
+   # Generate random data
+   X = np.random.rand(100, 2)
+
+   # Define a custom MDS solver using NetworkX
+   def custom_mds_solver(n, edges, nb_edges, random_state=None):
+      start = time.time()
+      graph = nx.Graph(edges)
+      centers = list(nx.algorithms.dominating_set(graph))
+      centers.sort()
+      end = time.time()
+      return centers, end - start
+
+   # Create an instance of MdsClustering with the custom MDS solver
+   rad = RadiusClustering(manner="approx", radius=0.5)
+   rad.set_solver(custom_mds_solver)
+
+   # Fit the model to the data
+   rad.fit(X)
+
+   # Get cluster labels
+   labels = rad.labels_
+
+   print(labels)
+
+.. note::
+   The custom MDS solver should accept the same parameters as the default solvers, including the number of points `n`, the edges of the graph `edges`, the number of edges `nb_edges`, and an optional `random_state` parameter for reproducibility. It should return a list of centers and the time taken to compute them.
+   The `set_solver` method will check that the custom solver is compatible with the expected input format and return type, and will use it to perform clustering.
+   If the custom solver is not compatible, it will raise a `ValueError` with a descriptive message.
+
+.. attention::
+   We cannot guarantee that the custom MDS solver will produce the same results as the default solvers, especially if it is not purposely designed to solve the Minimum Dominating Set problem but rather just finds a dominating set. The results may vary depending on the implementation and the specific characteristics of the dataset.
+   As an example, a benchmark of our solutions and a custom one using NetworkX is available in the `Example Gallery` section of the documentation, which shows that the custom solver may produce different results than the default solvers, especially in terms of the number of clusters and the time taken to compute them.
+   However, it can be useful for specific use cases where performance is a concern or when you have a custom implementation that fits your needs better.
+

examples/plot_benchmark_custom.py

@@ -0,0 +1,230 @@
+"""
+=====================================================================================
+Benchmark of Radius Clustering using multiple datasets and comparison with custom MDS
+=====================================================================================
+
+This example demonstrates how to implement a custom solver for the MDS problem
+and use it within the Radius Clustering framework.
+Plus, it compares the results of a naive implementation using the 
+`NetworkX` library with the Radius Clustering implementation.
+
+The example includes:
+    1. Defining the custom MDS solver.
+    2. Defining datasets to test the clustering.
+    3. Applying Radius clustering on the datasets using the custom MDS solver.
+    4. Ensure this solution works.
+    5. Establish a benchmark procedure to compare the Radius clustering with a naive implementation using `NetworkX`.
+    6. Comparing the results in terms of :
+        - Execution time
+        - Number of cluster found
+    7. Visualizing the benchmark results.
+    8. Visualizing the clustering results.
+
+This example is useful for understanding how to implement a custom MDS solver
+and how to perform an advanced usage of the package.
+"""
+# Author: Haenn Quentin
+# SPDX-License-Identifier: MIT
+
+# %%
+# Import necessary libraries
+# --------------------------
+# 
+# Since this example is a benchmark, we need to import the necessary libraries
+# to perform the benchmark, including `NetworkX` for the naive implementation,
+# `matplotlib` for visualization, and `sklearn` for the datasets.
+
+
+import networkx as nx
+import numpy as np
+import matplotlib.pyplot as plt
+import time
+import warnings
+
+from sklearn.datasets import fetch_openml
+from radius_clustering import RadiusClustering
+from sklearn.metrics import pairwise_distances_argmin
+
+warnings.filterwarnings("ignore", category=RuntimeWarning, module="sklearn")
+# %%
+# Define a custom MDS solver
+# --------------------------
+#
+# We define a custom MDS solver that uses the `NetworkX` library to compute the MDS.
+# Note the signature of the function is identical to the one used in the `RadiusClustering` class.
+
+
+def custom_solver(n: int, edges: np.ndarray, nb_edges: int, random_state=None):
+    """
+    Custom MDS solver using NetworkX to compute the MDS problem.
+    
+    Parameters:
+    -----------
+    n : int
+        The number of points in the dataset.
+    edges : np.ndarray
+        The edges of the graph, flattened into a 1D array.
+    nb_edges : int
+        The number of edges in the graph.
+    random_state : int | None
+        The random state to use for reproducibility.
+        
+    Returns:
+    --------
+    centers : list
+        A sorted list of the centers of the clusters.
+    mds_exec_time : float
+        The execution time of the MDS algorithm in seconds.
+    """
+    G = nx.Graph()
+    G.add_edges_from(edges)
+    
+    start_time = time.time()
+    centers = list(nx.algorithms.dominating.dominating_set(G))
+    mds_exec_time = time.time() - start_time
+
+    centers = sorted(centers)
+
+    return centers, mds_exec_time
+
+
+# %%
+# Define datasets to test the clustering
+# --------------------------------------
+# 
+# We will use 4 datasets to test the clustering:
+# 1. Iris dataset
+# 2. Wine dataset
+# 3. Breast Cancer dataset (WDBC)
+# 4. Vehicle dataset
+# These are common datasets used in machine learning and lead to pretty fast results.
+# Structure of the variable `DATASETS`:
+# - The key is the name of the dataset.
+# - The value is a tuple containing:
+#   - The dataset fetched from OpenML.
+#   - The radius to use for the Radius clustering. (determined in literature, see references on home page)
+#
+
+
+DATASETS = {
+    "iris": (fetch_openml(name="iris", version=1, as_frame=False), 1.43),
+    "wine": (fetch_openml(name="wine", version=1, as_frame=False), 232.09),
+    "glass": (fetch_openml(name="glass", version=1, as_frame=False), 3.94),
+    "ionosphere": (fetch_openml(name="ionosphere", version=1, as_frame=False), 5.46),
+    "breast_cancer": (fetch_openml(name="wdbc", version=1, as_frame=False), 1197.42),
+    "synthetic": (fetch_openml(name="synthetic_control", version=1, as_frame=False), 70.12),
+    "vehicle": (fetch_openml(name="vehicle", version=1, as_frame=False), 155.05),
+    "yeast": (fetch_openml(name="yeast", version=1, as_frame=False), 0.4235),
+}
+
+# %%
+# Define the benchmark procedure
+# --------------------------------------
+#
+# We define a function to perform the benchmark on the datasets.
+# The procedure is as follows:
+# 1. Creates an instance of RadiusClustering for each solver.
+# 2. For each instance, fit the algorithm on each dataset.
+# 3. Store the execution time and the number of clusters found for each dataset.
+# 4. Return the results as a dictionary.
+
+
+def benchmark_radius_clustering():
+    results = {}
+    exact = RadiusClustering(manner="exact", radius=1.43)
+    approx = RadiusClustering(manner="approx", radius=1.43)
+    custom = RadiusClustering(
+        manner="custom", radius=1.43
+    )
+    custom.set_solver(custom_solver) # Set the custom solver
+    algorithms = [exact, approx, custom]
+    # Loop through each algorithm and dataset
+    for algo in algorithms:
+        algo_results = {}
+        time_algo = []
+        clusters_algo = []
+        # Loop through each dataset
+        for name, (dataset, radius) in DATASETS.items():
+            X = dataset.data
+            # set the radius for the dataset considered
+            setattr(algo, "radius", radius)
+            # Fit the algorithm
+            t0 = time.time()
+            algo.fit(X)
+            t_algo = time.time() - t0
+
+            # Store the results
+            time_algo.append(t_algo)
+            clusters_algo.append(len(algo.centers_))
+        algo_results["time"] = time_algo
+        algo_results["clusters"] = clusters_algo
+        results[algo.manner] = algo_results
+
+    return results
+
+
+# %%
+# Run the benchmark and plot the results
+# --------------------------------------
+# We run the benchmark and plot the results for each dataset.
+
+
+results = benchmark_radius_clustering()
+
+# Plot the results
+fig, axs = plt.subplot_mosaic(
+    [
+        ["time", "time", "time", "time"],
+        ["iris", "wine", "breast_cancer", "vehicle"],
+        ["glass", "ionosphere", "synthetic", "yeast"],
+    ],
+    layout="constrained",
+    figsize=(12, 8),
+)
+fig.suptitle("Benchmark of Radius Clustering Solvers", fontsize=16)
+
+axs['time'].set_yscale('log')  # Use logarithmic scale for better visibility
+for algo, algo_results in results.items():
+    # Plot execution time
+    axs['time'].plot(
+        DATASETS.keys(),
+        algo_results["time"],
+        marker='o',
+        label=algo,
+    )
+    # Plot number of clusters
+
+for i, (name, (dataset, _)) in enumerate(DATASETS.items()):
+    axs[name].bar(
+        results.keys(),
+        [results[algo]["clusters"][i] for algo in results.keys()],
+        label=name,
+    )
+    axs[name].axhline(
+        y=len(set(dataset.target)),  # Number of unique classes in the dataset
+        label="True number of clusters",
+        color='r',
+        linestyle='--',
+    )
+    axs[name].set_title(name)
+    axs[name].set_xlabel("Algorithms")
+
+axs["iris"].set_ylabel("Number of clusters")
+axs["glass"].set_ylabel("Number of clusters")
+
+axs['time'].set_title("Execution Time (log scale)")
+axs['time'].set_xlabel("Datasets")
+axs['time'].set_ylabel("Time (seconds)")
+axs['time'].legend(title="Algorithms")
+plt.tight_layout()
+plt.show()
+
+
+# %%
+# Conclusion
+# ----------
+#
+# In this example, we applied Radius clustering to the Iris and Wine datasets and compared it with KMeans clustering.
+# We visualized the clustering results and the difference between the two clustering algorithms.
+# We saw that Radius Clustering can lead to smaller clusters than kmeans, which produces much more equilibrate clusters.
+# The difference plot can be very useful to see where the two clustering algorithms differ.

pyproject.toml

@@ -61,6 +61,7 @@ dev = [
 ]
 
 doc = [
+    "networkx>=3.3",
     "sphinx>=8.1.3",
     "sphinx_gallery>=0.18.0",
     "sphinx-copybutton>=0.5.2",

src/radius_clustering/algorithms.py

@@ -42,6 +42,7 @@ def clustering_approx(
 
         3. Use this random integer as the seed for the C++ code of the MDS solver.
 
+        
         This ensures that the seed passed to the C++ code is always an integer,
         which is required by the MDS solver, and allows for
         reproducibility of the results.