scikit-learn · kyrajeep · Mar 30, 2023 · Feb 17, 2024 · Jul 8, 2024 · Jul 12, 2024
diff --git a/sklearn/metrics/_dist_metrics.pyx.tp b/sklearn/metrics/_dist_metrics.pyx.tp
@@ -232,6 +232,7 @@ cdef class DistanceMetric:
 # metric mappings
 #  These map from metric id strings to class names
 METRIC_MAPPING{{name_suffix}} = {
+    'precomputed': PrecomputedDistanceMatrix{{name_suffix}}
     'euclidean': EuclideanDistance{{name_suffix}},
     'l2': EuclideanDistance{{name_suffix}},
     'minkowski': MinkowskiDistance{{name_suffix}},
@@ -359,13 +360,17 @@ cdef class DistanceMetric{{name_suffix}}(DistanceMetric):
 
     **User-defined distance:**
 
-    ===========    ===============    =======
-    identifier     class name         args
-    -----------    ---------------    -------
-    "pyfunc"       PyFuncDistance     func
-    ===========    ===============    =======
+    ===========    ===============            =======
+    identifier     class name                 args
+    -----------    ---------------            -------
+    "precomputed"  PrecomputedDistanceMatrix  precomputed
+    "pyfunc"       PyFuncDistance             func
+    ===========    ===============            =======
 
-    Here ``func`` is a function which takes two one-dimensional numpy
+    "precomputed" indicates that the user has the distance computed 
+    and wants to pass in the precomputed as an argument.
+
+    ``func`` is a function which takes two one-dimensional numpy
     arrays, and returns a distance.  Note that in order to be used within
     the BallTree, the distance must be a true metric:
     i.e. it must satisfy the following properties

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_argkmin_classmode.pyx.tp b/sklearn/metrics/_pairwise_distances_reduction/_argkmin_classmode.pyx.tp
@@ -13,6 +13,7 @@ from ._classmode cimport WeightingStrategy
 {{for name_suffix in ["32", "64"]}}
 from ._argkmin cimport ArgKmin{{name_suffix}}
 from ._datasets_pair cimport DatasetsPair{{name_suffix}}
+from ._datasets_pair cimport PrecomputedDistanceMatrix{{name_suffix}}
 
 cdef class ArgKminClassMode{{name_suffix}}(ArgKmin{{name_suffix}}):
     """

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_base.pxd.tp b/sklearn/metrics/_pairwise_distances_reduction/_base.pxd.tp
@@ -20,8 +20,7 @@ cdef class BaseDistancesReduction{{name_suffix}}:
     Implementations inherit from this template and may override the several
     defined hooks as needed in order to easily extend functionality with
     minimal redundant code.
-    """
-
+    """    
     cdef:
         readonly DatasetsPair{{name_suffix}} datasets_pair
 

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_base.pyx.tp b/sklearn/metrics/_pairwise_distances_reduction/_base.pyx.tp
@@ -127,6 +127,9 @@ cdef class BaseDistancesReduction{{name_suffix}}:
     Implementations inherit from this template and may override the several
     defined hooks as needed in order to easily extend functionality with
     minimal redundant code.
+
+    If metric is 'precomputed' and the precomputed matrix is provided, 
+    a subclass must be able to access it through the compute method.
     """
 
     def __init__(
@@ -137,7 +140,6 @@ cdef class BaseDistancesReduction{{name_suffix}}:
      ):
         cdef:
             intp_t X_n_full_chunks, Y_n_full_chunks
-
         if chunk_size is None:
             chunk_size = get_config().get("pairwise_dist_chunk_size", 256)
 

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_datasets_pair.pxd.tp b/sklearn/metrics/_pairwise_distances_reduction/_datasets_pair.pxd.tp
@@ -29,6 +29,11 @@ cdef class DatasetsPair{{name_suffix}}:
     cdef float64_t surrogate_dist(self, intp_t i, intp_t j) noexcept nogil
 
 
+cdef class PrecomputedDistanceMatrix{{name_suffix}}(DatasetsPair{{name_suffix}}):
+    cdef:
+        const {{INPUT_DTYPE_t}}[:, ::1] distance_matrix
+
+
 cdef class DenseDenseDatasetsPair{{name_suffix}}(DatasetsPair{{name_suffix}}):
     cdef:
         const {{INPUT_DTYPE_t}}[:, ::1] X

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_datasets_pair.pyx.tp b/sklearn/metrics/_pairwise_distances_reduction/_datasets_pair.pyx.tp
@@ -53,8 +53,8 @@ cdef class DatasetsPair{{name_suffix}}:
     @classmethod
     def get_for(
         cls,
-        X,
-        Y,
+        X = None,
+        Y = None,
         metric="euclidean",
         dict metric_kwargs=None,
     ) -> DatasetsPair{{name_suffix}}:
@@ -98,6 +98,9 @@ cdef class DatasetsPair{{name_suffix}}:
             metric_kwargs = copy.copy(metric_kwargs)
             metric_kwargs.pop("X_norm_squared", None)
             metric_kwargs.pop("Y_norm_squared", None)
+        if metric = precomputed:
+            return PrecomputedDistanceMatrix{{name_suffix}}(precomputed)
+
         cdef:
             {{DistanceMetric}} distance_metric = DistanceMetric.get_metric(
                 metric,
@@ -158,6 +161,43 @@ cdef class DatasetsPair{{name_suffix}}:
         # TODO: add "with gil: raise" here when supporting Cython 3.0
         return -1
 
+
+@final
+cdef class PrecomputedDistanceMatrix{{name_suffix}}(DatasetsPair{{name_suffix}}):
+    """A subclass of DatasetsPair 
+
+    Parameters: must receive precomputed_distance: ndarray of shape
+        (n_samples_X, n_samples_Y),
+        Must be C-contiguous. 
+    """
+
+    def __init__(
+        self,
+        const {{INPUT_DTYPE_t}}[:, ::1] precomputed_distance,  
+    ):
+        super().__init__(
+            distance_metric=DistanceMetric{{name_suffix}}(),
+            n_features=0,  
+        )
+        # This array has already been checked.
+        self.distance_matrix = precomputed_distance
+
+    @final
+    cdef intp_t n_samples_X(self) noexcept nogil:
+        return self.distance_matrix.shape[0]
+
+    @final
+    cdef intp_t n_samples_Y(self) noexcept nogil:
+        return self.distance_matrix.shape[1]
+
+    @final
+    cdef float64_t surrogate_dist(self, intp_t i, intp_t j) noexcept nogil:
+        return self.distance_matrix[i, j]
+
+    @final
+    cdef float64_t dist(self, intp_t i, intp_t j) noexcept nogil:
+        return self.distance_matrix[i, j]
+
 @final
 cdef class DenseDenseDatasetsPair{{name_suffix}}(DatasetsPair{{name_suffix}}):
     """Compute distances between row vectors of two arrays.

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_dispatcher.py b/sklearn/metrics/_pairwise_distances_reduction/_dispatcher.py
@@ -81,10 +81,12 @@ def valid_metrics(cls) -> List[str]:
             "hamming",
             *BOOL_METRICS,
         }
-        return sorted(({"sqeuclidean"} | set(METRIC_MAPPING64.keys())) - excluded)
+        return sorted(
+            ({"sqeuclidean", "precomputed"} | set(METRIC_MAPPING64.keys())) - excluded
+        )
 
     @classmethod
-    def is_usable_for(cls, X, Y, metric) -> bool:
+    def is_usable_for(cls, X=None, Y=None, metric="euclidean") -> bool:
         """Return True if the dispatcher can be used for the
         given parameters.
 
@@ -96,6 +98,8 @@ def is_usable_for(cls, X, Y, metric) -> bool:
         Y : {ndarray, sparse matrix} of shape (n_samples_Y, n_features)
             Input data.
 
+        precomputed: ndarray of shape (n_samples_X, n_samples_Y)
+
         metric : str, default='euclidean'
             The distance metric to use.
             For a list of available metrics, see the documentation of
@@ -105,7 +109,15 @@ def is_usable_for(cls, X, Y, metric) -> bool:
         -------
         True if the dispatcher can be used, else False.
         """
-
+        if metric == "precomputed":
+            if X is not None and Y is None:
+                is_usable = True
+            else:
+                is_usable = False
+
+        # is_usable = (X is not None and Y is not None) ^ bool(precomputed)
+        if is_usable == False:
+            return is_usable
         # FIXME: the current Cython implementation is too slow for a large number of
         # features. We temporarily disable it to fallback on SciPy's implementation.
         # See: https://github.com/scikit-learn/scikit-learn/issues/28191
@@ -188,9 +200,9 @@ class ArgKmin(BaseDistancesReductionDispatcher):
     @classmethod
     def compute(
         cls,
-        X,
-        Y,
-        k,
+        X=None,
+        Y=None,
+        k=None,
         metric="euclidean",
         chunk_size=None,
         metric_kwargs=None,
@@ -277,6 +289,25 @@ def compute(
         for the concrete implementation are therefore freed when this classmethod
         returns.
         """
+        """
+        if X is None and Y is None and precomputed_matrix is None:
+            raise ValueError("Either X and Y or precomputed_matrix must be provided.")
+        elif X is not None and Y is not None and precomputed_matrix is not None:
+            raise ValueError(
+                "Only one of X and Y or precomputed_matrix must be provided."
+            )
+        elif X is None and Y is not None:
+            raise ValueError("Y should not be provided without X.")
+        elif X is not None and Y is None:
+            raise ValueError("X should not be provided without Y.")
+        """
+
+        if metric == "precomputed":
+            if X is None:
+                raise ValueError("X should be provided as a precomputed value")
+            if Y is not None:
+                raise ValueError("Y should not be provided as a precomputed value")
+
         if X.dtype == Y.dtype == np.float64:
             return ArgKmin64.compute(
                 X=X,
@@ -326,9 +357,9 @@ class RadiusNeighbors(BaseDistancesReductionDispatcher):
     @classmethod
     def compute(
         cls,
-        X,
-        Y,
-        radius,
+        X=None,
+        Y=None,
+        radius=None,
         metric="euclidean",
         chunk_size=None,
         metric_kwargs=None,
@@ -421,6 +452,24 @@ def compute(
         for the concrete implementation are therefore freed when this classmethod
         returns.
         """
+        """
+        if X is None and Y is None and precomputed is None:
+            raise ValueError("Either X and Y or precomputed must be provided.")
+        elif X is not None and Y is not None and precomputed is not None:
+            raise ValueError("Only one of X and Y or precomputed must be provided.")
+        elif X is None and Y is not None:
+            raise ValueError("Y should not be provided without X.")
+        elif X is not None and Y is None:
+            raise ValueError("X should not be provided without Y.")
+        elif precomputed:
+            return precomputed
+        """
+        if metric == "precomputed":
+            if X is None:
+                raise ValueError("X should be provided as a precomputed value")
+            if Y is not None:
+                raise ValueError("Y should not be provided as a precomputed value")
+
         if X.dtype == Y.dtype == np.float64:
             return RadiusNeighbors64.compute(
                 X=X,

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_radius_neighbors.pyx.tp b/sklearn/metrics/_pairwise_distances_reduction/_radius_neighbors.pyx.tp
@@ -101,7 +101,7 @@ cdef class RadiusNeighbors{{name_suffix}}(BaseDistancesReduction{{name_suffix}})
              # Fall back on a generic implementation that handles most scipy
              # metrics by computing the distances between 2 vectors at a time.
             pda = RadiusNeighbors{{name_suffix}}(
-                datasets_pair=DatasetsPair{{name_suffix}}.get_for(X, Y, metric, metric_kwargs),
+                datasets_pair=DatasetsPair{{name_suffix}}.get_for(X, Y, precomputed, metric, metric_kwargs),
                 radius=radius,
                 chunk_size=chunk_size,
                 strategy=strategy,

diff --git a/sklearn/metrics/_pairwise_distances_reduction/_radius_neighbors_classmode.pyx.tp b/sklearn/metrics/_pairwise_distances_reduction/_radius_neighbors_classmode.pyx.tp
@@ -48,7 +48,7 @@ cdef class RadiusNeighborsClassMode{{name_suffix}}(RadiusNeighbors{{name_suffix}
         # Use a generic implementation that handles most scipy
         # metrics by computing the distances between 2 vectors at a time.
         pda = RadiusNeighborsClassMode{{name_suffix}}(
-            datasets_pair=DatasetsPair{{name_suffix}}.get_for(X, Y, metric, metric_kwargs),
+            datasets_pair=DatasetsPair{{name_suffix}}.get_for(X, Y, precomputed, metric, metric_kwargs),
             radius=radius,
             chunk_size=chunk_size,
             strategy=strategy,