adding support for custom solvers

Author: quentinhaenn

.coverage

@@ -18,6 +18,14 @@ Radius clustering is a Python package that implements clustering under radius co
 - Supports radius-constrained clustering
 - Provides options for exact and approximate solutions
 
+## Roadmap
+
+- [ ] Version 2.0.0beta:
+    - [x] Add support for custom MDS solvers
+    - [ ] Improve documentation and examples
+    - [ ] Add iterative algorithm in both exact and approximate versions, which will allow to use the package in a more flexible way, especially when not knowing the radius beforehand.
+    - [ ] Add more examples and tutorials
+
 ## Installation
 
 You can install Radius Clustering using pip:

README.md

@@ -45,16 +45,28 @@ def clustering_approx(
         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.
+    
+    .. note::
+        This function uses the approximation method to solve the MDS problem.
+        See [casado]_ for more details.
 
     Parameters:
     -----------
     n : int
         The number of points in the dataset.
-
-    Notes:
-    ------
-    This function uses the approximation method to solve the MDS problem.
-    See [casado]_ for more details.
+    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.
+        If None, a default value of 42 is used.
+    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.
     """
     result = solve_mds(
         n, edges.flatten().astype(np.int32), nb_edges, random_state
@@ -63,7 +75,7 @@ def clustering_approx(
     mds_exec_time = result["Time"]
     return centers, mds_exec_time
 
-def clustering_exact(n: int, edges: np.ndarray, nb_edges: int) -> None:
+def clustering_exact(n: int, edges: np.ndarray, nb_edges: int, seed: None = None) -> None:
     """
     Perform exact MDS clustering.
 
@@ -78,6 +90,20 @@ def clustering_exact(n: int, edges: np.ndarray, nb_edges: int) -> None:
     -----------
     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.
+    seed : None
+        This parameter is not used in the exact method, but it is kept for
+        compatibility with the approximate method.
+
+    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.
     """
     centers, mds_exec_time = py_emos_main(
         edges.flatten(), n, nb_edges

src/radius_clustering/algorithms.py

@@ -75,6 +75,10 @@ class RadiusClustering(ClusterMixin, BaseEstimator):
     """
 
     _estimator_type = "clusterer"
+    _algorithms = {
+        "exact": clustering_exact,
+        "approx": clustering_approx,
+    }
 
     def __init__(
         self,
@@ -211,7 +215,7 @@ def fit(self, X: np.ndarray, y: None = None, metric: str | callable = "euclidean
             np.uint32
         )  # Edges in the adjacency matrix
         # uint32 is used to use less memory. Max number of features is 2^32-1
-
+        self.clusterer_ = self._algorithms.get(self.manner, self._algorithms["approx"])
         self._clustering()
         self._compute_effective_radius()
         self._compute_labels()
@@ -253,16 +257,16 @@ def _clustering(self):
         Perform the clustering using either the exact or approximate MDS method.
         """
         n = self.X_checked_.shape[0]
-        if self.manner != "exact" and self.manner != "approx":
-            raise ValueError("Invalid manner. Choose either 'exact' or 'approx'.")
-        if self.manner == "exact":
-            self.centers_, self.mds_exec_time_ = clustering_exact(n, self.edges_, self.nb_edges_)
-        else:
+        if self.manner not in self._algorithms:
+            raise ValueError(f"Invalid manner. Please choose in {list(self._algorithms.keys())}.")
+        if self.clusterer_ == clustering_approx:
             if self.random_state is None:
                 self.random_state = 42
             self.random_state_ = check_random_state(self.random_state)
             seed = self.random_state_.randint(np.iinfo(np.int32).max)
-            self.centers_, self.mds_exec_time_ = clustering_approx(n, self.edges_, self.nb_edges_, seed)
+        else:
+            seed = None
+        self.centers_, self.mds_exec_time_ = self.clusterer_(n, self.edges_, self.nb_edges_, seed)
 
     def _compute_effective_radius(self):
         """
@@ -282,3 +286,52 @@ def _compute_labels(self):
 
         min_dist = np.min(distances, axis=1)
         self.labels_[min_dist > self.radius] = -1
+
+    def set_solver(self, solver: callable) -> None:
+        """
+        Set a custom solver for resolving the MDS problem.
+        This method allows users to replace the default MDS solver with a custom one.
+
+        .. important::
+            The custom solver must accept the same parameters as the default solvers
+            and return a tuple containing the cluster centers and the execution time.
+            e.g., it should have the signature:
+            ```python
+            def custom_solver(
+                        n: int,
+                        edges: np.ndarray,
+                        nb_edges: int,
+                        random_state: int | None = None
+                    ) -> tuple[list, float]:
+                # Custom implementation details
+                centers = [...]
+                exec_time = ...
+                # Return the centers and execution time
+                return centers, exec_time
+            ```
+        
+        Parameters:
+        ----------
+        solver : callable
+            The custom solver function to use for MDS clustering.
+            It should accept the same parameters as the default solvers
+            and return a tuple containing the cluster centers and the execution time.
+
+        Raises:
+        -------
+        ValueError
+            If the provided solver does not have the correct signature.
+        """
+        if not callable(solver):
+            raise ValueError("The provided solver must be callable.")
+        
+        # Check if the solver has the correct signature
+        try:
+            n = 3
+            edges = np.array([[0, 1], [1, 2], [2, 0]])
+            nb_edges = edges.shape[0]
+            solver(n, edges, nb_edges, random_state=None)
+        except Exception as e:
+            raise ValueError(f"The provided solver does not have the correct signature: {e}") from e
+        self.manner = "custom"
+        self._algorithms["custom"] = solver

src/radius_clustering/radius_clustering.py

@@ -84,10 +84,10 @@ def test_radius_clustering_invalid_manner():
     """
     Test that an error is raised when an invalid manner is provided.
     """
-    with pytest.raises(ValueError, match="Invalid manner. Choose either 'exact' or 'approx'."):
+    with pytest.raises(ValueError):
         RadiusClustering(manner="invalid", radius=1.43).fit([[0, 1], [1, 0], [2, 1]])
 
-    with pytest.raises(ValueError, match="Invalid manner. Choose either 'exact' or 'approx'."):
+    with pytest.raises(ValueError):
         RadiusClustering(manner="", radius=1.43).fit([[0, 1], [1, 0], [2, 1]])
 
 
@@ -102,4 +102,60 @@ def test_radius_clustering_invalid_radius():
         RadiusClustering(manner="approx", radius=0.0).fit([[0, 1], [1, 0], [2, 1]])
 
     with pytest.raises(ValueError, match="Radius must be a positive float."):
-        RadiusClustering(manner="exact", radius="invalid").fit([[0, 1], [1, 0], [2, 1]])
+        RadiusClustering(manner="exact", radius="invalid").fit([[0, 1], [1, 0], [2, 1]])
+
+def test_radius_clustering_fit_without_data():
+    """
+    Test that an error is raised when fitting without data.
+    """
+    clustering = RadiusClustering(manner="exact", radius=1.5)
+    with pytest.raises(ValueError):
+        clustering.fit(None)
+
+def test_radius_clustering_new_clusterer():
+    """
+    Test that a custom clusterer can be set within the RadiusClustering class.
+    """
+    def custom_clusterer(n, edges, nb_edges, random_state=None):
+        # A mock custom clusterer that returns a fixed set of centers
+        # and a fixed execution time
+        return [0, 1], 0.1
+    clustering = RadiusClustering(manner="exact", radius=1.5)
+    # Set the custom clusterer
+    assert hasattr(clustering, 'set_solver'), "RadiusClustering should have a set_solver method."
+    assert callable(clustering.set_solver), "set_solver should be callable."
+    clustering.set_solver(custom_clusterer)
+    # Fit the clustering with the custom clusterer
+    X = np.array([[0, 1],
+                  [1, 0],
+                  [2, 1]])
+    clustering.fit(X)
+    assert clustering.clusterer_ == custom_clusterer, "The custom clusterer should be set correctly."
+    # Check that the labels are assigned correctly
+    assert len(clustering.labels_) == X.shape[0], "Labels length should match number of samples."
+    assert clustering.nb_edges_ > 0, "There should be edges in the graph."
+    assert clustering.centers_ == [0, 1], "The centers should match the custom clusterer's output."
+    assert clustering.mds_exec_time_ == 0.1, "The MDS execution time should match the custom clusterer's output."
+
+def test_invalid_clusterer():
+    """
+    Test that an error is raised when an invalid clusterer is set.
+    """
+    clustering = RadiusClustering(manner="exact", radius=1.5)
+    with pytest.raises(ValueError, match="The provided solver must be callable."):
+        clustering.set_solver("not_a_callable")
+
+    with pytest.raises(ValueError, match="The provided solver must be callable."):
+        clustering.set_solver(12345)  # Not a callable
+    with pytest.raises(ValueError, match="The provided solver must be callable."):
+        clustering.set_solver(None)
+
+    def invalid_signature():
+        return [0, 1], 0.1
+    
+    with pytest.raises(ValueError):
+        clustering.set_solver(invalid_signature)
+    def invalid_clusterer(n, edges, nb_edges):
+        return [0, 1], 0.1
+    with pytest.raises(ValueError):
+        clustering.set_solver(invalid_clusterer)