Refactor num_dims in n_components and add deprecation

Author: William de Vazelhes

metric_learn/_util.py

@@ -407,11 +407,11 @@ def validate_vector(u, dtype=None):
   return u
 
 
-def _check_num_dims(n_features, num_dims):
-  """Checks that num_dims is less than n_features and deal with the None
+def _check_n_components(n_features, n_components):
+  """Checks that n_components is less than n_features and deal with the None
   case"""
-  if num_dims is None:
+  if n_components is None:
     return n_features
-  if 0 < num_dims <= n_features:
+  if 0 < n_components <= n_features:
     return n_features
-  raise ValueError('Invalid num_dims, must be in [1, %d]' % n_features)
+  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,

metric_learn/covariance.py

@@ -21,7 +21,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

@@ -145,7 +145,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`.)
 
@@ -213,7 +213,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`.)
   """

metric_learn/lfda.py

@@ -18,7 +18,7 @@
 from sklearn.metrics import pairwise_distances
 from sklearn.base import TransformerMixin
 
-from ._util import _check_num_dims
+from ._util import _check_n_components
 from .base_metric import MahalanobisMixin
 
 
@@ -29,23 +29,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')
@@ -59,6 +65,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
@@ -75,12 +82,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)
 
-    dim = _check_num_dims(d, 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

@@ -17,15 +17,16 @@
 from sklearn.metrics import euclidean_distances
 from sklearn.base import TransformerMixin
 
-from ._util import _check_num_dims
+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, num_dims=None):
+               verbose=False, preprocessor=None, n_components=None,
+               num_dims='deprecated'):
     """Initialize the LMNN object.
 
     Parameters
@@ -39,6 +40,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
@@ -48,6 +58,7 @@ 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)
 
@@ -56,21 +67,26 @@ def __init__(self, k=3, min_iter=50, max_iter=1000, learn_rate=1e-7,
 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
-    output_dim = _check_num_dims(num_dims, self.num_dims)
+    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(output_dim, 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 +288,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

@@ -139,7 +139,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`.)
   """
@@ -175,7 +175,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`.)
   """

metric_learn/mlkr.py

@@ -33,19 +33,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.
@@ -63,6 +69,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
@@ -79,6 +86,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
@@ -87,7 +99,7 @@ def fit(self, X, y):
                            % (n, y.shape[0]))
 
       A = self.A0
-      m = self.num_dims
+      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`.)
   """

metric_learn/nca.py

@@ -14,7 +14,7 @@
 from sklearn.utils.fixes import logsumexp
 from sklearn.base import TransformerMixin
 
-from ._util import _check_num_dims
+from ._util import _check_n_components
 from .base_metric import MahalanobisMixin
 
 EPS = np.finfo(float).eps
@@ -28,19 +28,24 @@ class NCA(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, max_iter=100, tol=None, verbose=False,
-               preprocessor=None):
+  def __init__(self, n_components=None, num_dims='deprecated', max_iter=100,
+               tol=None, verbose=False, preprocessor=None):
     """Neighborhood Components Analysis
 
     Parameters
     ----------
-    num_dims : int, optional (default=None)
-      Embedding dimensionality. If None, will be set to ``n_features``
-      (``d``) at fit time.
+    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.
 
     max_iter : int, optional (default=100)
       Maximum number of iterations done by the optimization algorithm.
@@ -51,6 +56,7 @@ def __init__(self, num_dims=None, max_iter=100, tol=None, verbose=False,
     verbose : bool, optional (default=False)
       Whether to print progress messages or not.
     """
+    self.n_components = n_components
     self.num_dims = num_dims
     self.max_iter = max_iter
     self.tol = tol
@@ -62,16 +68,21 @@ def fit(self, X, y):
     X: data matrix, (n x d)
     y: scalar labels, (n)
     """
+    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, labels = self._prepare_inputs(X, y, ensure_min_samples=2)
     n, d = X.shape
-    num_dims = _check_num_dims(d, self.num_dims)
+    n_components = _check_n_components(d, self.n_components)
 
     # Measure the total training time
     train_time = time.time()
 
     # Initialize A to a scaling matrix
-    A = np.zeros((num_dims, d))
-    np.fill_diagonal(A, 1./(np.maximum(X.max(axis=0)-X.min(axis=0), EPS)))
+    A = np.zeros((n_components, d))
+    np.fill_diagonal(A, 1. / (np.maximum(X.max(axis=0) - X.min(axis=0), EPS)))
 
     # Run NCA
     mask = labels[:, np.newaxis] == labels[np.newaxis, :]
@@ -120,7 +131,7 @@ def _loss_grad_lbfgs(self, A, X, mask, sign=1.0):
     start_time = time.time()
 
     A = A.reshape(-1, X.shape[1])
-    X_embedded = np.dot(X, A.T)  # (n_samples, num_dims)
+    X_embedded = np.dot(X, A.T)  # (n_samples, n_components)
     # Compute softmax distances
     p_ij = pairwise_distances(X_embedded, squared=True)
     np.fill_diagonal(p_ij, np.inf)