[MRG] Uniformize num_dims to n_components and add it for LMNN (#193)

* Uniformize num_dims and add it for LMNN

* MAINT: fix imports

* Fix: fix test_num_dims

* MAINT: Address #193 (review)

* Refactor num_dims in n_components and add deprecation

* FIX make some tests work

* FIX Make tests work (fix deprecation messages and fix RCA example)

* Remove unused import

* Revert "Remove unused import"

This reverts commit 81c9a8d.

* Fix import

* FIX fix some tests

* Allow more general sign switching in test_lfda

Author: wdevazelhes

metric_learn/_util.py

@@ -411,3 +411,13 @@ def validate_vector(u, dtype=None):
   if u.ndim > 1:
     raise ValueError("Input vector should be 1-D.")
   return u
+
+
+def _check_n_components(n_features, n_components):
+  """Checks that n_components is less than n_features and deal with the None
+  case"""
+  if n_components is None:
+    return n_features
+  if 0 < n_components <= n_features:
+    return n_components
+  raise ValueError('Invalid n_components, must be in [1, %d]' % n_features)

metric_learn/base_metric.py

@@ -172,7 +172,7 @@ class MahalanobisMixin(six.with_metaclass(ABCMeta, BaseMetricLearner,
 
   Attributes
   ----------
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The learned linear transformation ``L``.
   """
 
@@ -232,7 +232,7 @@ def transform(self, X):
 
     Returns
     -------
-    X_embedded : `numpy.ndarray`, shape=(n_samples, num_dims)
+    X_embedded : `numpy.ndarray`, shape=(n_samples, n_components)
       The embedded data points.
     """
     X_checked = check_input(X, type_of_inputs='classic', estimator=self,
@@ -288,7 +288,7 @@ def get_mahalanobis_matrix(self):
 
     Returns
     -------
-    M : `numpy.ndarray`, shape=(n_components, n_features)
+    M : `numpy.ndarray`, shape=(n_features, n_features)
       The copy of the learned Mahalanobis matrix.
     """
     return self.transformer_.T.dot(self.transformer_)

metric_learn/covariance.py

@@ -22,7 +22,7 @@ class Covariance(MahalanobisMixin, TransformerMixin):
 
   Attributes
   ----------
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
   """

metric_learn/itml.py

@@ -150,7 +150,7 @@ class ITML(_BaseITML, _PairsClassifierMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
 
@@ -218,7 +218,7 @@ class ITML_Supervised(_BaseITML, TransformerMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
   """
@@ -292,11 +292,11 @@ def fit(self, X, y, random_state=np.random, bounds=None):
     if self.num_labeled != 'deprecated':
       warnings.warn('"num_labeled" parameter is not used.'
                     ' It has been deprecated in version 0.5.0 and will be'
-                    'removed in 0.6.0', DeprecationWarning)
+                    ' removed in 0.6.0', DeprecationWarning)
     if self.bounds != 'deprecated':
       warnings.warn('"bounds" parameter from initialization is not used.'
                     ' It has been deprecated in version 0.5.0 and will be'
-                    'removed in 0.6.0. Use the "bounds" parameter of this '
+                    ' removed in 0.6.0. Use the "bounds" parameter of this '
                     'fit method instead.', DeprecationWarning)
     X, y = self._prepare_inputs(X, y, ensure_min_samples=2)
     num_constraints = self.num_constraints

metric_learn/lfda.py

@@ -16,6 +16,8 @@
 from six.moves import xrange
 from sklearn.metrics import pairwise_distances
 from sklearn.base import TransformerMixin
+
+from ._util import _check_n_components
 from .base_metric import MahalanobisMixin
 
 
@@ -26,23 +28,29 @@ class LFDA(MahalanobisMixin, TransformerMixin):
 
   Attributes
   ----------
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The learned linear transformation ``L``.
   '''
 
-  def __init__(self, num_dims=None, k=None, embedding_type='weighted',
-               preprocessor=None):
+  def __init__(self, n_components=None, num_dims='deprecated',
+               k=None, embedding_type='weighted', preprocessor=None):
     '''
     Initialize LFDA.
 
     Parameters
     ----------
-    num_dims : int, optional
-        Dimensionality of reduced space (defaults to dimension of X)
+    n_components : int or None, optional (default=None)
+        Dimensionality of reduced space (if None, defaults to dimension of X).
+
+    num_dims : Not used
+
+        .. deprecated:: 0.5.0
+          `num_dims` was deprecated in version 0.5.0 and will
+          be removed in 0.6.0. Use `n_components` instead.
 
     k : int, optional
         Number of nearest neighbors used in local scaling method.
-        Defaults to min(7, num_dims - 1).
+        Defaults to min(7, n_components - 1).
 
     embedding_type : str, optional
         Type of metric in the embedding space (default: 'weighted')
@@ -56,6 +64,7 @@ def __init__(self, num_dims=None, k=None, embedding_type='weighted',
     '''
     if embedding_type not in ('weighted', 'orthonormalized', 'plain'):
       raise ValueError('Invalid embedding_type: %r' % embedding_type)
+    self.n_components = n_components
     self.num_dims = num_dims
     self.embedding_type = embedding_type
     self.k = k
@@ -72,17 +81,17 @@ def fit(self, X, y):
     y : (n,) array-like
         Class labels, one per point of data.
     '''
+    if self.num_dims != 'deprecated':
+      warnings.warn('"num_dims" parameter is not used.'
+                    ' It has been deprecated in version 0.5.0 and will be'
+                    ' removed in 0.6.0. Use "n_components" instead',
+                    DeprecationWarning)
     X, y = self._prepare_inputs(X, y, ensure_min_samples=2)
     unique_classes, y = np.unique(y, return_inverse=True)
     n, d = X.shape
     num_classes = len(unique_classes)
 
-    if self.num_dims is None:
-      dim = d
-    else:
-      if not 0 < self.num_dims <= d:
-        raise ValueError('Invalid num_dims, must be in [1,%d]' % d)
-      dim = self.num_dims
+    dim = _check_n_components(d, self.n_components)
 
     if self.k is None:
       k = min(7, d - 1)

metric_learn/lmnn.py

@@ -19,14 +19,17 @@
 from six.moves import xrange
 from sklearn.metrics import euclidean_distances
 from sklearn.base import TransformerMixin
+
+from ._util import _check_n_components
 from .base_metric import MahalanobisMixin
 
 
 # commonality between LMNN implementations
 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, preprocessor=None):
+               verbose=False, preprocessor=None, n_components=None,
+               num_dims='deprecated'):
     """Initialize the LMNN object.
 
     Parameters
@@ -40,6 +43,15 @@ def __init__(self, k=3, min_iter=50, max_iter=1000, learn_rate=1e-7,
     preprocessor : array-like, shape=(n_samples, n_features) or callable
         The preprocessor to call to get tuples from indices. If array-like,
         tuples will be formed like this: X[indices].
+
+    n_components : int or None, optional (default=None)
+        Dimensionality of reduced space (if None, defaults to dimension of X).
+
+    num_dims : Not used
+
+        .. deprecated:: 0.5.0
+          `num_dims` was deprecated in version 0.5.0 and will
+          be removed in 0.6.0. Use `n_components` instead.
     """
     self.k = k
     self.min_iter = min_iter
@@ -49,27 +61,35 @@ def __init__(self, k=3, min_iter=50, max_iter=1000, learn_rate=1e-7,
     self.convergence_tol = convergence_tol
     self.use_pca = use_pca
     self.verbose = verbose
+    self.n_components = n_components
+    self.num_dims = num_dims
     super(_base_LMNN, self).__init__(preprocessor)
 
 
 # slower Python version
 class python_LMNN(_base_LMNN):
 
   def fit(self, X, y):
+    if self.num_dims != 'deprecated':
+      warnings.warn('"num_dims" parameter is not used.'
+                    ' It has been deprecated in version 0.5.0 and will be'
+                    ' removed in 0.6.0. Use "n_components" instead',
+                    DeprecationWarning)
     k = self.k
     reg = self.regularization
     learn_rate = self.learn_rate
 
     X, y = self._prepare_inputs(X, y, dtype=float,
                                 ensure_min_samples=2)
-    num_pts, num_dims = X.shape
+    num_pts, d = X.shape
+    output_dim = _check_n_components(d, self.n_components)
     unique_labels, label_inds = np.unique(y, return_inverse=True)
     if len(label_inds) != num_pts:
       raise ValueError('Must have one label per point.')
     self.labels_ = np.arange(len(unique_labels))
     if self.use_pca:
       warnings.warn('use_pca does nothing for the python_LMNN implementation')
-    self.transformer_ = np.eye(num_dims)
+    self.transformer_ = np.eye(output_dim, d)
     required_k = np.bincount(label_inds).min()
     if self.k > required_k:
       raise ValueError('not enough class labels for specified k'
@@ -272,7 +292,7 @@ class LMNN(_base_LMNN):
     n_iter_ : `int`
         The number of iterations the solver has run.
 
-    transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+    transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
         The learned linear transformation ``L``.
     """
 

metric_learn/lsml.py

@@ -146,7 +146,7 @@ class LSML(_BaseLSML, _QuadrupletsClassifierMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
   """
@@ -182,7 +182,7 @@ class LSML_Supervised(_BaseLSML, TransformerMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
   """
@@ -241,7 +241,7 @@ def fit(self, X, y, random_state=np.random):
     if self.num_labeled != 'deprecated':
       warnings.warn('"num_labeled" parameter is not used.'
                     ' It has been deprecated in version 0.5.0 and will be'
-                    'removed in 0.6.0', DeprecationWarning)
+                    ' removed in 0.6.0', DeprecationWarning)
     X, y = self._prepare_inputs(X, y, ensure_min_samples=2)
     num_constraints = self.num_constraints
     if num_constraints is None:

metric_learn/mlkr.py

@@ -23,6 +23,8 @@
 
 
 from sklearn.metrics import pairwise_distances
+
+from metric_learn._util import _check_n_components
 from .base_metric import MahalanobisMixin
 
 EPS = np.finfo(float).eps
@@ -36,19 +38,25 @@ class MLKR(MahalanobisMixin, TransformerMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The learned linear transformation ``L``.
   """
 
-  def __init__(self, num_dims=None, A0=None, tol=None, max_iter=1000,
-               verbose=False, preprocessor=None):
+  def __init__(self, n_components=None, num_dims='deprecated', A0=None,
+               tol=None, max_iter=1000, verbose=False, preprocessor=None):
     """
     Initialize MLKR.
 
     Parameters
     ----------
-    num_dims : int, optional
-        Dimensionality of reduced space (defaults to dimension of X)
+    n_components : int or None, optional (default=None)
+        Dimensionality of reduced space (if None, defaults to dimension of X).
+
+    num_dims : Not used
+
+        .. deprecated:: 0.5.0
+          `num_dims` was deprecated in version 0.5.0 and will
+          be removed in 0.6.0. Use `n_components` instead.
 
     A0: array-like, optional
         Initialization of transformation matrix. Defaults to PCA loadings.
@@ -66,6 +74,7 @@ def __init__(self, num_dims=None, A0=None, tol=None, max_iter=1000,
         The preprocessor to call to get tuples from indices. If array-like,
         tuples will be formed like this: X[indices].
     """
+    self.n_components = n_components
     self.num_dims = num_dims
     self.A0 = A0
     self.tol = tol
@@ -82,6 +91,11 @@ def fit(self, X, y):
       X : (n x d) array of samples
       y : (n) data labels
       """
+      if self.num_dims != 'deprecated':
+        warnings.warn('"num_dims" parameter is not used.'
+                      ' It has been deprecated in version 0.5.0 and will be'
+                      ' removed in 0.6.0. Use "n_components" instead',
+                      DeprecationWarning)
       X, y = self._prepare_inputs(X, y, y_numeric=True,
                                   ensure_min_samples=2)
       n, d = X.shape
@@ -90,7 +104,8 @@ def fit(self, X, y):
                            % (n, y.shape[0]))
 
       A = self.A0
-      m = self.num_dims
+      m = _check_n_components(d, self.n_components)
+      m = self.n_components
       if m is None:
           m = d
       if A is None:

metric_learn/mmc.py

@@ -356,7 +356,7 @@ class MMC(_BaseMMC, _PairsClassifierMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
 
@@ -406,7 +406,7 @@ class MMC_Supervised(_BaseMMC, TransformerMixin):
   n_iter_ : `int`
       The number of iterations the solver has run.
 
-  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+  transformer_ : `numpy.ndarray`, shape=(n_components, n_features)
       The linear transformation ``L`` deduced from the learned Mahalanobis
       metric (See function `transformer_from_metric`.)
   """
@@ -469,7 +469,7 @@ def fit(self, X, y, random_state=np.random):
     if self.num_labeled != 'deprecated':
       warnings.warn('"num_labeled" parameter is not used.'
                     ' It has been deprecated in version 0.5.0 and will be'
-                    'removed in 0.6.0', DeprecationWarning)
+                    ' removed in 0.6.0', DeprecationWarning)
     X, y = self._prepare_inputs(X, y, ensure_min_samples=2)
     num_constraints = self.num_constraints
     if num_constraints is None: