[MRG] Refactor the metric() method

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/base_metric.py

@@ -1,3 +1,5 @@
+from numpy.linalg import cholesky
+from scipy.spatial.distance import euclidean, _validate_vector
 from sklearn.base import BaseEstimator
 from sklearn.utils.validation import _is_arraylike
 from sklearn.metrics import roc_auc_score
@@ -34,6 +36,13 @@ 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 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 +94,24 @@ 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 returns the learned metric between 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).
+
+    Returns
+    -------
+    metric_fun : function
+      The function described above.
+
+    See Also
+    --------
+    score_pairs : a method that returns the metric between several pairs of
+      points. But 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 +173,16 @@ 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 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,8 +214,57 @@ def transform(self, X):
                              accept_sparse=True)
     return X_checked.dot(self.transformer_.T)
 
-  def metric(self):
-    return self.transformer_.T.dot(self.transformer_)
+  def get_metric(self):
+    """Returns a function that returns the learned metric between 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).
+
+    Returns
+    -------
+    metric_fun : function
+      The function described above.
+
+    See Also
+    --------
+    score_pairs : a method that returns the metric between several pairs of
+      points. But 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 distances computation.
+      v : array-like, shape=(n_features,)
+        The second point involved in the distances 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 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()

test/test_mahalanobis_mixin.py

@@ -3,7 +3,7 @@
 import pytest
 import numpy as np
 from numpy.testing import assert_array_almost_equal
-from scipy.spatial.distance import pdist, squareform
+from scipy.spatial.distance import pdist, squareform, euclidean
 from sklearn import clone
 from sklearn.utils import check_random_state
 from sklearn.utils.testing import set_random_state
@@ -167,3 +167,47 @@ def test_embed_is_linear(estimator, build_dataset):
                             model.transform(X[10:20]))
   assert_array_almost_equal(model.transform(5 * X[:10]),
                             5 * model.transform(X[:10]))
+
+
+@pytest.mark.parametrize('estimator, build_dataset', metric_learners,
+                         ids=ids_metric_learners)
+def test_get_metric_equivalent_to_transform_and_euclidean(estimator,
+                                                          build_dataset):
+  """Tests that the get_metric method of mahalanobis metric learners is the
+  euclidean distance in the transformed space
+  """
+  rng = np.random.RandomState(42)
+  input_data, labels, _, X = build_dataset()
+  model = clone(estimator)
+  set_random_state(model)
+  model.fit(input_data, labels)
+  metric = model.get_metric()
+  n_features = X.shape[1]
+  a, b = (rng.randn(n_features), rng.randn(n_features))
+  euc_dist = euclidean(model.transform(a[None]), model.transform(b[None]))
+  assert (euc_dist - metric(a, b)) / euc_dist < 1e-15
+
+
+@pytest.mark.parametrize('estimator, build_dataset', metric_learners,
+                         ids=ids_metric_learners)
+def test_get_metric_is_pseudo_metric(estimator, build_dataset):
+  """Tests that the get_metric method of mahalanobis metric learners returns a
+  pseudo-metric (metric but without one side of the equivalence of
+  the identity of indiscernables property)
+  """
+  rng = np.random.RandomState(42)
+  input_data, labels, _, X = build_dataset()
+  model = clone(estimator)
+  set_random_state(model)
+  model.fit(input_data, labels)
+  metric = model.get_metric()
+
+  n_features = X.shape[1]
+  a, b, c = (rng.randn(n_features) for _ in range(3))
+  assert metric(a, b) >= 0  # positivity
+  assert metric(a, b) == metric(b, a)  # symmetry
+  # one side of identity indiscernables: x == y => d(x, y) == 0. The other
+  # side is not always true for Mahalanobis distances.
+  assert metric(a, a) == 0
+  # triangular inequality
+  assert metric(a, c) <= metric(a, b) + metric(b, c)

test/test_transformer_metric_conversion.py

@@ -20,60 +20,60 @@ def test_cov(self):
     cov = Covariance()
     cov.fit(self.X)
     L = cov.transformer_
-    assert_array_almost_equal(L.T.dot(L), cov.metric())
+    assert_array_almost_equal(L.T.dot(L), cov.get_mahalanobis_matrix())
 
   def test_lsml_supervised(self):
     seed = np.random.RandomState(1234)
     lsml = LSML_Supervised(num_constraints=200)
     lsml.fit(self.X, self.y, random_state=seed)
     L = lsml.transformer_
-    assert_array_almost_equal(L.T.dot(L), lsml.metric())
+    assert_array_almost_equal(L.T.dot(L), lsml.get_mahalanobis_matrix())
 
   def test_itml_supervised(self):
     seed = np.random.RandomState(1234)
     itml = ITML_Supervised(num_constraints=200)
     itml.fit(self.X, self.y, random_state=seed)
     L = itml.transformer_
-    assert_array_almost_equal(L.T.dot(L), itml.metric())
+    assert_array_almost_equal(L.T.dot(L), itml.get_mahalanobis_matrix())
 
   def test_lmnn(self):
     lmnn = LMNN(k=5, learn_rate=1e-6, verbose=False)
     lmnn.fit(self.X, self.y)
     L = lmnn.transformer_
-    assert_array_almost_equal(L.T.dot(L), lmnn.metric())
+    assert_array_almost_equal(L.T.dot(L), lmnn.get_mahalanobis_matrix())
 
   def test_sdml_supervised(self):
     seed = np.random.RandomState(1234)
     sdml = SDML_Supervised(num_constraints=1500)
     sdml.fit(self.X, self.y, random_state=seed)
     L = sdml.transformer_
-    assert_array_almost_equal(L.T.dot(L), sdml.metric())
+    assert_array_almost_equal(L.T.dot(L), sdml.get_mahalanobis_matrix())
 
   def test_nca(self):
     n = self.X.shape[0]
     nca = NCA(max_iter=(100000//n))
     nca.fit(self.X, self.y)
     L = nca.transformer_
-    assert_array_almost_equal(L.T.dot(L), nca.metric())
+    assert_array_almost_equal(L.T.dot(L), nca.get_mahalanobis_matrix())
 
   def test_lfda(self):
     lfda = LFDA(k=2, num_dims=2)
     lfda.fit(self.X, self.y)
     L = lfda.transformer_
-    assert_array_almost_equal(L.T.dot(L), lfda.metric())
+    assert_array_almost_equal(L.T.dot(L), lfda.get_mahalanobis_matrix())
 
   def test_rca_supervised(self):
     seed = np.random.RandomState(1234)
     rca = RCA_Supervised(num_dims=2, num_chunks=30, chunk_size=2)
     rca.fit(self.X, self.y, random_state=seed)
     L = rca.transformer_
-    assert_array_almost_equal(L.T.dot(L), rca.metric())
+    assert_array_almost_equal(L.T.dot(L), rca.get_mahalanobis_matrix())
 
   def test_mlkr(self):
     mlkr = MLKR(num_dims=2)
     mlkr.fit(self.X, self.y)
     L = mlkr.transformer_
-    assert_array_almost_equal(L.T.dot(L), mlkr.metric())
+    assert_array_almost_equal(L.T.dot(L), mlkr.get_mahalanobis_matrix())
 
 
 if __name__ == '__main__':