MAINT: Adress #96 (review)

- replace embed by transform and add always the input X in calling the function
- mutualize _transformer_from_metric not to be overwritten in MMC
- improve test_mahalanobis_mixin.test_score_pairs_pairwise according to #96 (comment)
- improve test_mahalanobis_mixin.check_is_distance_matrix
- correct typos and nitpicks

Author: William de Vazelhes

examples/sandwich.py

@@ -30,7 +30,7 @@ def sandwich_demo():
 
   for ax_num, ml in enumerate(mls, start=3):
     ml.fit(x, y)
-    tx = ml.transform()
+    tx = ml.transform(x)
     ml_knn = nearest_neighbors(tx, k=2)
     ax = plt.subplot(3, 2, ax_num)
     plot_sandwich_data(tx, y, axis=ax)

metric_learn/base_metric.py

@@ -1,5 +1,5 @@
 from numpy.linalg import cholesky
-from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.base import BaseEstimator
 from sklearn.utils.validation import check_array
 from sklearn.metrics import roc_auc_score
 import numpy as np
@@ -28,9 +28,9 @@ def score_pairs(self, pairs):
     """
 
 
-class MetricTransformer(TransformerMixin):
+class MetricTransformer():
 
-  def transform(self, X=None):
+  def transform(self, X):
     """Applies the metric transformation.
 
     Parameters
@@ -43,15 +43,10 @@ def transform(self, X=None):
     transformed : (n x d) matrix
         Input data transformed to the metric space by :math:`XL^{\\top}`
     """
-    if X is None:
-      X = self.X_
-    else:
-      X = check_array(X, accept_sparse=True)
-    L = self.transformer_
-    return X.dot(L.T)
 
 
-class MahalanobisMixin(six.with_metaclass(ABCMeta, BaseMetricLearner)):
+class MahalanobisMixin(six.with_metaclass(ABCMeta, BaseMetricLearner,
+                                          MetricTransformer)):
   """Mahalanobis metric learning algorithms.
 
   Algorithm that learns a Mahalanobis (pseudo) distance :math:`d_M(x, x')`,
@@ -91,12 +86,12 @@ def score_pairs(self, pairs):
     scores: `numpy.ndarray` of shape=(n_pairs,)
       The learned Mahalanobis distance for every pair.
     """
-    pairwise_diffs = self.embed(pairs[..., 1, :] - pairs[..., 0, :])  # (for
-    #  MahalanobisMixin, the embedding is linear so we can just embed the
+    pairwise_diffs = self.transform(pairs[..., 1, :] - pairs[..., 0, :])
+    # (for MahalanobisMixin, the embedding is linear so we can just embed the
     # difference)
     return np.sqrt(np.sum(pairwise_diffs**2, axis=-1))
 
-  def embed(self, X):
+  def transform(self, X):
     """Embeds data points in the learned linear embedding space.
 
     Transforms samples in ``X`` into ``X_embedded``, samples inside a new
@@ -113,21 +108,37 @@ def embed(self, X):
     X_embedded : `numpy.ndarray`, shape=(n_samples, num_dims)
       The embedded data points.
     """
-    return X.dot(self.transformer_.T)
+    X_checked = check_array(X, accept_sparse=True, ensure_2d=False)
+    return X_checked.dot(self.transformer_.T)
 
   def metric(self):
     return self.transformer_.T.dot(self.transformer_)
 
-  def transformer_from_metric(self, metric):
+  def _transformer_from_metric(self, metric):
     """Computes the transformation matrix from the Mahalanobis matrix.
 
-    L = cholesky(M).T
+    Since by definition the metric `M` is positive semi-definite (PSD), it
+    admits a Cholesky decomposition: L = cholesky(M).T. However, currently the
+    computation of the Cholesky decomposition used does not support
+    non-definite matrices. If the metric is not definite, this method will
+    return L = V.T w^( -1/2), with M = V*w*V.T being the eigenvector
+    decomposition of M with the eigenvalues in the diagonal matrix w and the
+    columns of V being the eigenvectors. If M is diagonal, this method will
+    just return its elementwise square root (since the diagonalization of
+    the matrix is itself).
 
     Returns
     -------
-    L : upper triangular (d x d) matrix
+    L : (d x d) matrix
     """
-    return cholesky(metric).T
+
+    if np.allclose(metric, np.diag(np.diag(metric))):
+      return np.sqrt(metric)
+    elif not np.isclose(np.linalg.det(metric), 0):
+      return cholesky(metric).T
+    else:
+      w, V = np.linalg.eigh(metric)
+      return V.T * np.sqrt(np.maximum(0, w[:, None]))
 
 
 class _PairsClassifierMixin(BaseMetricLearner):
@@ -182,6 +193,24 @@ def score(self, pairs, y):
 class _QuadrupletsClassifierMixin(BaseMetricLearner):
 
   def predict(self, quadruplets):
+    """Predicts the ordering between sample distances in input quadruplets.
+
+    For each quadruplet, returns 1 if the quadruplet is in the right order (
+    first pair is more similar than second pair), and -1 if not.
+
+    Parameters
+    ----------
+    quadruplets : array-like, shape=(n_constraints, 4, n_features)
+      Input quadruplets.
+
+    Returns
+    -------
+    prediction : `numpy.ndarray` of floats, shape=(n_constraints,)
+      Predictions of the ordering of pairs, for each quadruplet.
+    """
+    return np.sign(self.decision_function(quadruplets))
+
+  def decision_function(self, quadruplets):
     """Predicts differences between sample distances in input quadruplets.
 
     For each quadruplet of samples, computes the difference between the learned
@@ -194,15 +223,12 @@ def predict(self, quadruplets):
 
     Returns
     -------
-    prediction : `numpy.ndarray` of floats, shape=(n_constraints,)
+    decision_function : `numpy.ndarray` of floats, shape=(n_constraints,)
       Metric differences.
     """
     return (self.score_pairs(quadruplets[..., :2, :]) -
             self.score_pairs(quadruplets[..., 2:, :]))
 
-  def decision_function(self, quadruplets):
-    return self.predict(quadruplets)
-
   def score(self, quadruplets, y=None):
     """Computes score on input quadruplets
 
@@ -222,4 +248,4 @@ def score(self, quadruplets, y=None):
     score : float
       The quadruplets score.
     """
-    return - np.mean(np.sign(self.decision_function(quadruplets)))
+    return - np.mean(self.predict(quadruplets))

metric_learn/covariance.py

@@ -11,11 +11,12 @@
 from __future__ import absolute_import
 import numpy as np
 from sklearn.utils.validation import check_array
+from sklearn.base import TransformerMixin
 
-from .base_metric import MahalanobisMixin, MetricTransformer
+from .base_metric import MahalanobisMixin
 
 
-class Covariance(MetricTransformer, MahalanobisMixin):
+class Covariance(MahalanobisMixin, TransformerMixin):
   def __init__(self):
     pass
 
@@ -31,5 +32,5 @@ def fit(self, X, y=None):
     else:
       self.M_ = np.linalg.inv(self.M_)
 
-    self.transformer_ = self.transformer_from_metric(check_array(self.M_))
+    self.transformer_ = self._transformer_from_metric(check_array(self.M_))
     return self

metric_learn/itml.py

@@ -18,8 +18,8 @@
 from six.moves import xrange
 from sklearn.metrics import pairwise_distances
 from sklearn.utils.validation import check_array, check_X_y
-from .base_metric import (_PairsClassifierMixin, MetricTransformer,
-                          MahalanobisMixin)
+from sklearn.base import TransformerMixin
+from .base_metric import _PairsClassifierMixin, MahalanobisMixin
 from .constraints import Constraints, wrap_pairs
 from ._util import vector_norm
 
@@ -53,7 +53,7 @@ def __init__(self, gamma=1., max_iter=1000, convergence_threshold=1e-3,
 
   def _process_pairs(self, pairs, y, bounds):
     pairs, y = check_X_y(pairs, y, accept_sparse=False,
-                                      ensure_2d=False, allow_nd=True)
+                         ensure_2d=False, allow_nd=True)
 
     # check to make sure that no two constrained vectors are identical
     pos_pairs, neg_pairs = pairs[y == 1], pairs[y == -1]
@@ -129,7 +129,7 @@ def _fit(self, pairs, y, bounds=None):
       print('itml converged at iter: %d, conv = %f' % (it, conv))
     self.n_iter_ = it
 
-    self.transformer_ = self.transformer_from_metric(self.A_)
+    self.transformer_ = self._transformer_from_metric(self.A_)
     return self
 
 
@@ -155,7 +155,7 @@ def fit(self, pairs, y, bounds=None):
     return self._fit(pairs, y, bounds=bounds)
 
 
-class ITML_Supervised(_BaseITML, MetricTransformer):
+class ITML_Supervised(_BaseITML, TransformerMixin):
   """Information Theoretic Metric Learning (ITML)"""
   def __init__(self, gamma=1., max_iter=1000, convergence_threshold=1e-3,
                num_labeled=np.inf, num_constraints=None, bounds=None, A0=None,

metric_learn/lfda.py

@@ -17,11 +17,11 @@
 from six.moves import xrange
 from sklearn.metrics import pairwise_distances
 from sklearn.utils.validation import check_X_y
+from sklearn.base import TransformerMixin
+from .base_metric import MahalanobisMixin
 
-from .base_metric import MahalanobisMixin, MetricTransformer
 
-
-class LFDA(MahalanobisMixin, MetricTransformer):
+class LFDA(MahalanobisMixin, TransformerMixin):
   '''
   Local Fisher Discriminant Analysis for Supervised Dimensionality Reduction
   Sugiyama, ICML 2006

metric_learn/lmnn.py

@@ -16,12 +16,12 @@
 from six.moves import xrange
 from sklearn.utils.validation import check_X_y, check_array
 from sklearn.metrics import euclidean_distances
-
-from .base_metric import MahalanobisMixin, MetricTransformer
+from sklearn.base import TransformerMixin
+from .base_metric import MahalanobisMixin
 
 
 # commonality between LMNN implementations
-class _base_LMNN(MahalanobisMixin, MetricTransformer):
+class _base_LMNN(MahalanobisMixin, TransformerMixin):
   def __init__(self, k=3, min_iter=50, max_iter=1000, learn_rate=1e-7,
                regularization=0.5, convergence_tol=0.001, use_pca=True,
                verbose=False):
@@ -189,7 +189,7 @@ def _select_targets(self):
     return target_neighbors
 
   def _find_impostors(self, furthest_neighbors):
-    Lx = self.transform()
+    Lx = self.transform(self.X_)
     margin_radii = 1 + _inplace_paired_L2(Lx[furthest_neighbors], Lx)
     impostors = []
     for label in self.labels_[:-1]:
@@ -256,7 +256,7 @@ def fit(self, X, y):
         self._lmnn.train()
       else:
         self._lmnn.train(np.eye(X.shape[1]))
-      self.L_ = self._lmnn.get_linear_transform()
+      self.L_ = self._lmnn.get_linear_transform(X)
       return self
 
 except ImportError:

metric_learn/lsml.py

@@ -11,11 +11,10 @@
 import numpy as np
 import scipy.linalg
 from six.moves import xrange
-
+from sklearn.base import TransformerMixin
 from sklearn.utils.validation import check_array, check_X_y
 
-from .base_metric import (_QuadrupletsClassifierMixin, MetricTransformer,
-                          MahalanobisMixin)
+from .base_metric import _QuadrupletsClassifierMixin, MahalanobisMixin
 from .constraints import Constraints
 
 
@@ -95,7 +94,7 @@ def _fit(self, quadruplets, weights=None):
         print("Didn't converge after", it, "iterations. Final loss:", s_best)
     self.n_iter_ = it
 
-    self.transformer_ = self.transformer_from_metric(self.M_)
+    self.transformer_ = self._transformer_from_metric(self.M_)
     return self
 
   def _comparison_loss(self, metric):
@@ -147,7 +146,7 @@ def fit(self, quadruplets, weights=None):
     return self._fit(quadruplets, weights=weights)
 
 
-class LSML_Supervised(_BaseLSML, MetricTransformer):
+class LSML_Supervised(_BaseLSML, TransformerMixin):
   def __init__(self, tol=1e-3, max_iter=1000, prior=None, num_labeled=np.inf,
                num_constraints=None, weights=None, verbose=False):
     """Initialize the learner.

metric_learn/mlkr.py

@@ -10,16 +10,17 @@
 import numpy as np
 from scipy.optimize import minimize
 from scipy.spatial.distance import pdist, squareform
+from sklearn.base import TransformerMixin
 from sklearn.decomposition import PCA
 
 from sklearn.utils.validation import check_X_y
 
-from .base_metric import MahalanobisMixin, MetricTransformer
+from .base_metric import MahalanobisMixin
 
 EPS = np.finfo(float).eps
 
 
-class MLKR(MahalanobisMixin, MetricTransformer):
+class MLKR(MahalanobisMixin, TransformerMixin):
   """Metric Learning for Kernel Regression (MLKR)"""
   def __init__(self, num_dims=None, A0=None, epsilon=0.01, alpha=0.0001,
                max_iter=1000):

metric_learn/mmc.py

@@ -19,11 +19,10 @@
 from __future__ import print_function, absolute_import, division
 import numpy as np
 from six.moves import xrange
-
+from sklearn.base import TransformerMixin
 from sklearn.utils.validation import check_array, check_X_y
 
-from .base_metric import (_PairsClassifierMixin, MahalanobisMixin,
-                          MetricTransformer)
+from .base_metric import _PairsClassifierMixin, MahalanobisMixin
 from .constraints import Constraints, wrap_pairs
 from ._util import vector_norm
 
@@ -215,7 +214,7 @@ def _fit_full(self, pairs, y):
     self.A_[:] = A_old
     self.n_iter_ = cycle
 
-    self.transformer_ = self.transformer_from_metric(self.A_)
+    self.transformer_ = self._transformer_from_metric(self.A_)
     return self
 
   def _fit_diag(self, pairs, y):
@@ -275,7 +274,7 @@ def _fit_diag(self, pairs, y):
 
     self.A_ = np.diag(w)
 
-    self.transformer_ = self.transformer_from_metric(self.A_)
+    self.transformer_ = self._transformer_from_metric(self.A_)
     return self
 
   def _fD(self, neg_pairs, A):
@@ -355,24 +354,6 @@ def _D_constraint(self, neg_pairs, w):
       sum_deri2 / sum_dist - np.outer(sum_deri1, sum_deri1) / (sum_dist * sum_dist)
     )
 
-  def transformer_from_metric(self, metric):
-    """Computes the transformation matrix from the Mahalanobis matrix.
-    L = V.T * w^(-1/2), with A = V*w*V.T being the eigenvector decomposition of A with
-    the eigenvalues in the diagonal matrix w and the columns of V being the eigenvectors.
-
-    The Cholesky decomposition cannot be applied here, since MMC learns only a positive
-    *semi*-definite Mahalanobis matrix.
-
-    Returns
-    -------
-    L : (d x d) matrix
-    """
-    if self.diagonal:
-      return np.sqrt(metric)
-    else:
-      w, V = np.linalg.eigh(metric)
-      return V.T * np.sqrt(np.maximum(0, w[:, None]))
-
 
 class MMC(_BaseMMC, _PairsClassifierMixin):
 
@@ -394,7 +375,7 @@ def fit(self, pairs, y):
     return self._fit(pairs, y)
 
 
-class MMC_Supervised(_BaseMMC, MetricTransformer):
+class MMC_Supervised(_BaseMMC, TransformerMixin):
   """Mahalanobis Metric for Clustering (MMC)"""
   def __init__(self, max_iter=100, max_proj=10000, convergence_threshold=1e-6,
                num_labeled=np.inf, num_constraints=None,

metric_learn/nca.py

@@ -6,14 +6,15 @@
 from __future__ import absolute_import
 import numpy as np
 from six.moves import xrange
+from sklearn.base import TransformerMixin
 from sklearn.utils.validation import check_X_y
 
-from .base_metric import MahalanobisMixin, MetricTransformer
+from .base_metric import MahalanobisMixin
 
 EPS = np.finfo(float).eps
 
 
-class NCA(MahalanobisMixin, MetricTransformer):
+class NCA(MahalanobisMixin, TransformerMixin):
   def __init__(self, num_dims=None, max_iter=100, learning_rate=0.01):
     self.num_dims = num_dims
     self.max_iter = max_iter