Feature/improve test bench

docs/source/tdamapper.rst

@@ -41,6 +41,14 @@ tdamapper.utils.metrics
    :undoc-members:
    :show-inheritance:
 
+tdamapper.utils.vptree
+-----------------------
+
+.. automodule:: tdamapper.utils.vptree
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 tdamapper.plot
 --------------
 

src/tdamapper/cover.py

@@ -75,21 +75,56 @@ class BallCover(ProximityCover):
     Cover algorithm based on `ball proximity function` implemented as
     :class:`tdamapper.proximity.BallProximity`.
 
-    :param radius: The radius of the open balls, must be positive.
+    :param radius: The radius of the open balls. Must be a positive value.
     :type radius: float
-    :param metric: The (pseudo-)metric function that defines the distance
-        between points, must be symmetric, positive, and satisfy the
-        triangle-inequality, i.e.
-        :math:`metric(x, z) \leq metric(x, y) + metric(y, z)` for every x, y, z
-        in the dataset.
-    :type metric: Callable
-    :param flat: A flag that indicates whether to use a flat or a hierarchical
-        vantage point tree, defaults to False.
-    :type flat: bool, optional
+
+    :param metric: The metric used to define the distance between points.
+    Accepts any value compatible with `tdamapper.utils.metrics.get_metric`.
+    Defaults to 'euclidean'.
+    :type metric: str or callable
+
+    :param metric_params: Additional parameters for the metric function, to be
+    passed to `tdamapper.utils.metrics.get_metric`. Defaults to None.
+    :type metric_params: dict, optional
+
+    :param kind: Specifies whether to use a flat or a hierarchical vantage
+    point tree. Acceptable values are 'flat' or 'hierarchical'. Defaults to
+    'flat'.
+    :type kind: str
+
+    :param leaf_capacity: The maximum number of points in a leaf node of the
+    vantage point tree. Must be a positive value. Defaults to 1.
+    :type leaf_capacity: int
+
+    :param leaf_radius: The radius of the leaf nodes. If not specified, it
+    defaults to the value of `radius`. Must be a positive value. Defaults to
+    None.
+    :type leaf_radius: float, optional
+
+    :param pivoting: The method used for pivoting in the vantage point tree.
+    Acceptable values are None, 'random', or 'furthest'. Defaults to None.
+    :type pivoting: str or callable, optional
     """
 
-    def __init__(self, radius, metric, flat=True):
-        prox = BallProximity(radius=radius, metric=metric, flat=flat)
+    def __init__(
+        self,
+        radius,
+        metric='euclidean',
+        metric_params=None,
+        kind='flat',
+        leaf_capacity=1,
+        leaf_radius=None,
+        pivoting=None,
+    ):
+        prox = BallProximity(
+            radius=radius,
+            metric=metric,
+            metric_params=metric_params,
+            kind=kind,
+            leaf_capacity=leaf_capacity,
+            leaf_radius=leaf_radius,
+            pivoting=pivoting,
+        )
         super().__init__(proximity=prox)
 
 
@@ -99,21 +134,57 @@ class KNNCover(ProximityCover):
     :class:`tdamapper.proximity.KNNProximity`.
 
     :param neighbors: The number of neighbors to use for the KNN Proximity
-        function, must be positive and less than the length of the dataset.
+    function, must be positive and less than the length of the dataset.
     :type neighbors: int
-    :param metric: The (pseudo-)metric function that defines the distance
-        between points, must be symmetric, positive, and satisfy the
-        triangle-inequality, i.e.
-        :math:`metric(x, z) \leq metric(x, y) + metric(y, z)` for every x, y, z
-        in the dataset.
-    :type metric: Callable
-    :param flat: A flag that indicates whether to use a flat or a hierarchical
-        vantage point tree, defaults to False.
-    :type flat: bool, optional
+
+    :param metric: The metric used to define the distance between points.
+    Accepts any value compatible with `tdamapper.utils.metrics.get_metric`.
+    Defaults to 'euclidean'.
+    :type metric: str or callable
+
+    :param metric_params: Additional parameters for the metric function, to be
+    passed to `tdamapper.utils.metrics.get_metric`. Defaults to None.
+    :type metric_params: dict, optional
+
+    :param kind: Specifies whether to use a flat or a hierarchical vantage
+    point tree. Acceptable values are 'flat' or 'hierarchical'. Defaults to
+    'flat'.
+    :type kind: str
+
+    :param leaf_capacity: The maximum number of points in a leaf node of the
+    vantage point tree. If not specified, it defaults to the value of
+    `neighbors`. Must be a positive value. Defaults to None.
+    :type leaf_capacity: int, optional
+
+    :param leaf_radius: The radius of the leaf nodes. Must be a positive value.
+    Defaults to 0.0.
+    :type leaf_radius: float
+
+    :param pivoting: The method used for pivoting in the vantage point tree.
+    Acceptable values are None, 'random', or 'furthest'. Defaults to None.
+    :type pivoting: str or callable, optional
+
     """
 
-    def __init__(self, neighbors, metric, flat=True):
-        prox = KNNProximity(neighbors=neighbors, metric=metric, flat=flat)
+    def __init__(
+        self,
+        neighbors,
+        metric='euclidean',
+        metric_params=None,
+        kind='flat',
+        leaf_capacity=None,
+        leaf_radius=0.0,
+        pivoting=None,
+    ):
+        prox = KNNProximity(
+            neighbors=neighbors,
+            metric=metric,
+            metric_params=metric_params,
+            kind=kind,
+            leaf_capacity=leaf_capacity,
+            leaf_radius=leaf_radius,
+            pivoting=pivoting,
+        )
         super().__init__(proximity=prox)
 
 
@@ -123,21 +194,58 @@ class CubicalCover(ProximityCover):
     :class:`tdamapper.proximity.CubicalProximity`.
 
     :param n_intervals: The number of intervals to use for each dimension, must
-        be positive and less than or equal to the length of the dataset.
+    be positive and less than or equal to the length of the dataset.
     :type n_intervals: int
+
     :param overlap_frac: The fraction of overlap between adjacent intervals on
-        each dimension, must be in the range (0.0, 1.0).
+    each dimension, must be in the range (0.0, 1.0).
     :type overlap_frac: float
-    :param flat: A flag that indicates whether to use a flat or a hierarchical
-        vantage point tree, defaults to False.
-    :type flat: bool, optional
+
+    :param metric: The metric used to define the distance between points.
+    Accepts any value compatible with `tdamapper.utils.metrics.get_metric`.
+    Defaults to 'euclidean'.
+    :type metric: str or callable
+
+    :param metric_params: Additional parameters for the metric function, to be
+    passed to `tdamapper.utils.metrics.get_metric`. Defaults to None.
+    :type metric_params: dict, optional
+
+    :param kind: Specifies whether to use a flat or a hierarchical vantage
+    point tree. Acceptable values are 'flat' or 'hierarchical'. Defaults to
+    'flat'.
+    :type kind: str
+
+    :param leaf_capacity: The maximum number of points in a leaf node of the
+    vantage point tree. Must be a positive value. Defaults to 1.
+    :type leaf_capacity: int
+
+    :param leaf_radius: The radius of the leaf nodes. If not specified, it
+    defaults to the value of `radius`. Must be a positive value. Defaults to
+    None.
+    :type leaf_radius: float, optional
+
+    :param pivoting: The method used for pivoting in the vantage point tree.
+    Acceptable values are None, 'random', or 'furthest'. Defaults to None.
+    :type pivoting: str or callable, optional
     """
 
-    def __init__(self, n_intervals, overlap_frac, flat=True):
+    def __init__(
+        self,
+        n_intervals,
+        overlap_frac,
+        kind='flat',
+        leaf_capacity=1,
+        leaf_radius=None,
+        pivoting=None,
+    ):
         prox = CubicalProximity(
             n_intervals=n_intervals, 
             overlap_frac=overlap_frac,
-            flat=flat)
+            kind=kind,
+            leaf_capacity=leaf_capacity,
+            leaf_radius=leaf_radius,
+            pivoting=pivoting,
+        )
         super().__init__(proximity=prox)