[MRG] Refactor the metric() method

doc/conf.py

@@ -7,7 +7,8 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
     'numpydoc',
-    'sphinx_gallery.gen_gallery'
+    'sphinx_gallery.gen_gallery',
+    'sphinx.ext.doctest'
 ]
 
 templates_path = ['_templates']
@@ -35,3 +36,6 @@
 # Option to only need single backticks to refer to symbols
 default_role = 'any'
 
+# Option to hide doctests comments in the documentation (like # doctest:
+# +NORMALIZE_WHITESPACE for instance)
+trim_doctest_flags = True

doc/introduction.rst

@@ -38,6 +38,8 @@ generally formulated as an optimization problem where one seeks to find the
 parameters of a distance function that optimize some objective function
 measuring the agreement with the training data.
 
+.. _mahalanobis_distances:
+
 Mahalanobis Distances
 =====================
 

metric_learn/_util.py

@@ -349,3 +349,14 @@ def transformer_from_metric(metric):
   else:
     w, V = np.linalg.eigh(metric)
     return V.T * np.sqrt(np.maximum(0, w[:, None]))
+
+
+def validate_vector(u, dtype=None):
+  # replica of scipy.spatial.distance._validate_vector, for making scipy
+  # compatible functions on vectors (such as distances computations)
+  u = np.asarray(u, dtype=dtype, order='c').squeeze()
+  # Ensure values such as u=1 and u=[1] still return 1-D arrays.
+  u = np.atleast_1d(u)
+  if u.ndim > 1:
+    raise ValueError("Input vector should be 1-D.")
+  return u

metric_learn/base_metric.py

@@ -1,10 +1,13 @@
+from numpy.linalg import cholesky
+from scipy.spatial.distance import euclidean
 from sklearn.base import BaseEstimator
 from sklearn.utils.validation import _is_arraylike
 from sklearn.metrics import roc_auc_score
 import numpy as np
 from abc import ABCMeta, abstractmethod
 import six
-from ._util import ArrayIndexer, check_input
+from ._util import ArrayIndexer, check_input, validate_vector
+import warnings
 
 
 class BaseMetricLearner(six.with_metaclass(ABCMeta, BaseEstimator)):
@@ -34,6 +37,14 @@ def score_pairs(self, pairs):
     -------
     scores: `numpy.ndarray` of shape=(n_pairs,)
       The score of every pair.
+
+    See Also
+    --------
+    get_metric : a method that returns a function to compute the metric between
+      two points. The difference with `score_pairs` is that it works on two 1D
+      arrays and cannot use a preprocessor. Besides, the returned function is
+      independent of the metric learner and hence is not modified if the metric
+      learner is.
     """
 
   def check_preprocessor(self):
@@ -85,6 +96,47 @@ def _prepare_inputs(self, X, y=None, type_of_inputs='classic',
                        tuple_size=getattr(self, '_tuple_size', None),
                        **kwargs)
 
+  @abstractmethod
+  def get_metric(self):
+    """Returns a function that takes as input two 1D arrays and outputs the
+    learned metric score on these two points.
+
+    This function will be independent from the metric learner that learned it
+    (it will not be modified if the initial metric learner is modified),
+    and it can be directly plugged into the `metric` argument of
+    scikit-learn's estimators.
+
+    Returns
+    -------
+    metric_fun : function
+      The function described above.
+
+
+    Examples
+    --------
+    .. doctest::
+
+      >>> from metric_learn import NCA
+      >>> from sklearn.datasets import make_classification
+      >>> from sklearn.neighbors import KNeighborsClassifier
+      >>> nca = NCA()
+      >>> X, y = make_classification()
+      >>> nca.fit(X, y)
+      >>> knn = KNeighborsClassifier(metric=nca.get_metric())
+      >>> knn.fit(X, y) # doctest: +NORMALIZE_WHITESPACE
+      KNeighborsClassifier(algorithm='auto', leaf_size=30,
+        metric=<function MahalanobisMixin.get_metric.<locals>.metric_fun
+                at 0x...>,
+        metric_params=None, n_jobs=None, n_neighbors=5, p=2,
+        weights='uniform')
+
+    See Also
+    --------
+    score_pairs : a method that returns the metric score between several pairs
+      of points. Unlike `get_metric`, this is a method of the metric learner
+      and therefore can change if the metric learner changes. Besides, it can
+      use the metric learner's preprocessor, and works on concatenated arrays.
+    """
 
 class MetricTransformer(six.with_metaclass(ABCMeta)):
 
@@ -146,6 +198,17 @@ def score_pairs(self, pairs):
     -------
     scores: `numpy.ndarray` of shape=(n_pairs,)
       The learned Mahalanobis distance for every pair.
+
+    See Also
+    --------
+    get_metric : a method that returns a function to compute the metric between
+      two points. The difference with `score_pairs` is that it works on two 1D
+      arrays and cannot use a preprocessor. Besides, the returned function is
+      independent of the metric learner and hence is not modified if the metric
+      learner is.
+
+    :ref:`mahalanobis_distances` : The section of the project documentation
+      that describes Mahalanobis Distances.
     """
     pairs = check_input(pairs, type_of_inputs='tuples',
                         preprocessor=self.preprocessor_,
@@ -177,9 +240,87 @@ def transform(self, X):
                              accept_sparse=True)
     return X_checked.dot(self.transformer_.T)
 
+  def get_metric(self):
+    """Returns a function that takes as input two 1D arrays and outputs the
+    learned metric score on these two points.
+
+    This function will be independent from the metric learner that learned it
+    (it will not be modified if the initial metric learner is modified),
+    and it can be directly plugged into the `metric` argument of
+    scikit-learn's estimators.
+
+    Returns
+    -------
+    metric_fun : function
+      The function described above.
+
+    Examples
+    --------
+    .. doctest::
+
+      >>> from metric_learn import NCA
+      >>> from sklearn.datasets import make_classification
+      >>> from sklearn.neighbors import KNeighborsClassifier
+      >>> nca = NCA()
+      >>> X, y = make_classification()
+      >>> nca.fit(X, y)
+      >>> knn = KNeighborsClassifier(metric=nca.get_metric())
+      >>> knn.fit(X, y) # doctest: +NORMALIZE_WHITESPACE
+      KNeighborsClassifier(algorithm='auto', leaf_size=30,
+        metric=<function MahalanobisMixin.get_metric.<locals>.metric_fun
+                at 0x...>,
+        metric_params=None, n_jobs=None, n_neighbors=5, p=2,
+        weights='uniform')
+
+    See Also
+    --------
+    score_pairs : a method that returns the metric score between several pairs
+      of points. Unlike `get_metric`, this is a method of the metric learner
+      and therefore can change if the metric learner changes. Besides, it can
+      use the metric learner's preprocessor, and works on concatenated arrays.
+
+    :ref:`mahalanobis_distances` : The section of the project documentation
+      that describes Mahalanobis Distances.
+    """
+    transformer_T = self.transformer_.T.copy()
+
+    def metric_fun(u, v):
+      """This function computes the metric between u and v, according to the
+      previously learned metric.
+
+      Parameters
+      ----------
+      u : array-like, shape=(n_features,)
+        The first point involved in the distance computation.
+      v : array-like, shape=(n_features,)
+        The second point involved in the distance computation.
+      Returns
+      -------
+      distance: float
+        The distance between u and v according to the new metric.
+      """
+      u = validate_vector(u)
+      v = validate_vector(v)
+      return euclidean(u.dot(transformer_T), v.dot(transformer_T))
+    return metric_fun
+
   def metric(self):
+    # TODO: remove this method in version 0.6.0
+    warnings.warn(("`metric` is deprecated since version 0.5.0 and will be "
+                   "removed in 0.6.0. Use `get_mahalanobis_matrix` instead."),
+                  DeprecationWarning)
     return self.transformer_.T.dot(self.transformer_)
 
+  def get_mahalanobis_matrix(self):
+    """Returns a copy of the Mahalanobis matrix learned by the metric learner.
+
+    Returns
+    -------
+    M : `numpy.ndarray`, shape=(n_components, n_features)
+      The copy of the learned Mahalanobis matrix.
+    """
+    return self.transformer_.T.dot(self.transformer_).copy()
+
 
 class _PairsClassifierMixin(BaseMetricLearner):
 

test/metric_learn_test.py

@@ -273,7 +273,7 @@ def test_iris(self):
     self.assertLess(csep, 0.15)
 
     # Sanity checks for learned matrices.
-    self.assertEqual(lfda.metric().shape, (4, 4))
+    self.assertEqual(lfda.get_mahalanobis_matrix().shape, (4, 4))
     self.assertEqual(lfda.transformer_.shape, (2, 4))
 
 
@@ -348,14 +348,16 @@ def test_iris(self):
                 [+0.000868, +0.001468, -0.002021, -0.002879],
                 [-0.001195, -0.002021, +0.002782, +0.003964],
                 [-0.001703, -0.002879, +0.003964, +0.005648]]
-    assert_array_almost_equal(expected, mmc.metric(), decimal=6)
+    assert_array_almost_equal(expected, mmc.get_mahalanobis_matrix(),
+                              decimal=6)
 
     # Diagonal metric
     mmc = MMC(diagonal=True)
     mmc.fit(*wrap_pairs(self.iris_points, [a,b,c,d]))
     expected = [0, 0, 1.210220, 1.228596]
-    assert_array_almost_equal(np.diag(expected), mmc.metric(), decimal=6)
-
+    assert_array_almost_equal(np.diag(expected), mmc.get_mahalanobis_matrix(),
+                              decimal=6)
+
     # Supervised Full
     mmc = MMC_Supervised()
     mmc.fit(self.iris_points, self.iris_labels)

test/test_base_metric.py

@@ -1,5 +1,10 @@
+import pytest
 import unittest
 import metric_learn
+import numpy as np
+from sklearn import clone
+from sklearn.utils.testing import set_random_state
+from test.test_utils import ids_metric_learners, metric_learners
 
 
 class TestStringRepr(unittest.TestCase):
@@ -81,5 +86,82 @@ def test_mmc(self):
         num_labeled='deprecated', preprocessor=None, verbose=False)
 """.strip('\n'))
 
+
+@pytest.mark.parametrize('estimator, build_dataset', metric_learners,
+                         ids=ids_metric_learners)
+def test_get_metric_is_independent_from_metric_learner(estimator,
+                                                       build_dataset):
+  """Tests that the get_metric method returns a function that is independent
+  from the original metric learner"""
+  input_data, labels, _, X = build_dataset()
+  model = clone(estimator)
+  set_random_state(model)
+
+  # we fit the metric learner on it and then we compute the metric on some
+  # points
+  model.fit(input_data, labels)
+  metric = model.get_metric()
+  score = metric(X[0], X[1])
+
+  # then we refit the estimator on another dataset
+  model.fit(np.sin(input_data), labels)
+
+  # we recompute the distance between the two points: it should be the same
+  score_bis = metric(X[0], X[1])
+  assert score_bis == score
+
+
+@pytest.mark.parametrize('estimator, build_dataset', metric_learners,
+                         ids=ids_metric_learners)
+def test_get_metric_raises_error(estimator, build_dataset):
+  """Tests that the metric returned by get_metric raises errors similar to
+  the distance functions in scipy.spatial.distance"""
+  input_data, labels, _, X = build_dataset()
+  model = clone(estimator)
+  set_random_state(model)
+  model.fit(input_data, labels)
+  metric = model.get_metric()
+
+  list_test_get_metric_raises = [(X[0].tolist() + [5.2], X[1]),  # vectors with
+                                 # different dimensions
+                                 (X[0:4], X[1:5]),  # 2D vectors
+                                 (X[0].tolist() + [5.2], X[1] + [7.2])]
+  # vectors of same dimension but incompatible with what the metric learner
+  # was trained on
+
+  for u, v in list_test_get_metric_raises:
+    with pytest.raises(ValueError):
+      metric(u, v)
+
+
+@pytest.mark.parametrize('estimator, build_dataset', metric_learners,
+                         ids=ids_metric_learners)
+def test_get_metric_works_does_not_raise(estimator, build_dataset):
+  """Tests that the metric returned by get_metric does not raise errors (or
+  warnings) similarly to the distance functions in scipy.spatial.distance"""
+  input_data, labels, _, X = build_dataset()
+  model = clone(estimator)
+  set_random_state(model)
+  model.fit(input_data, labels)
+  metric = model.get_metric()
+
+  list_test_get_metric_doesnt_raise = [(X[0], X[1]),
+                                       (X[0].tolist(), X[1].tolist()),
+                                       (X[0][None], X[1][None])]
+
+  for u, v in list_test_get_metric_doesnt_raise:
+    with pytest.warns(None) as record:
+      metric(u, v)
+    assert len(record) == 0
+
+  # Test that the scalar case works
+  model.transformer_ = np.array([3.1])
+  metric = model.get_metric()
+  for u, v in [(5, 6.7), ([5], [6.7]), ([[5]], [[6.7]])]:
+    with pytest.warns(None) as record:
+      metric(u, v)
+    assert len(record) == 0
+
+
 if __name__ == '__main__':
   unittest.main()