Merge branch 'feat/mahalanobis_class' of https://github.com/wdevazelhes/metric-learn into feat/mahalanobis_class

Author: William de Vazelhes

metric_learn/_util.py

@@ -28,7 +28,7 @@ def check_tuples(tuples):
     The validated input.
   """
   # If input is scalar raise error
-  if len(tuples.shape) == 0:
+  if np.isscalar(tuples):
     raise ValueError(
       "Expected 3D array, got scalar instead. Cannot apply this function on "
       "scalars.")

metric_learn/base_metric.py

@@ -29,7 +29,7 @@ def score_pairs(self, pairs):
     """
 
 
-class MetricTransformer():
+class MetricTransformer(object):
 
   @abstractmethod
   def transform(self, X):
@@ -63,8 +63,8 @@ class MahalanobisMixin(six.with_metaclass(ABCMeta, BaseMetricLearner,
 
   Attributes
   ----------
-  transformer_ : `np.ndarray`, shape=(num_dims, n_features)
-    The learned linear transformation ``L``.
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
   """
 
   def score_pairs(self, pairs):
@@ -117,7 +117,7 @@ def transform(self, X):
   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.
 
     Since by definition the metric `M` is positive semi-definite (PSD), it
@@ -257,4 +257,4 @@ def score(self, quadruplets, y=None):
       The quadruplets score.
     """
     quadruplets = check_tuples(quadruplets)
-    return - np.mean(self.predict(quadruplets))
+    return -np.mean(self.predict(quadruplets))

metric_learn/covariance.py

@@ -17,6 +17,15 @@
 
 
 class Covariance(MahalanobisMixin, TransformerMixin):
+  """Covariance metric (baseline method)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
+
   def __init__(self):
     pass
 
@@ -32,5 +41,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

@@ -132,11 +132,19 @@ 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
 
 
 class ITML(_BaseITML, _PairsClassifierMixin):
+  """Information Theoretic Metric Learning (ITML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
 
   def fit(self, pairs, y, bounds=None):
     """Learn the ITML model.
@@ -159,7 +167,15 @@ def fit(self, pairs, y, bounds=None):
 
 
 class ITML_Supervised(_BaseITML, TransformerMixin):
-  """Information Theoretic Metric Learning (ITML)"""
+  """Supervised version of Information Theoretic Metric Learning (ITML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See `transformer_from_metric`.)
+  """
+
   def __init__(self, gamma=1., max_iter=1000, convergence_threshold=1e-3,
                num_labeled=np.inf, num_constraints=None, bounds=None, A0=None,
                verbose=False):
@@ -192,6 +208,7 @@ def __init__(self, gamma=1., max_iter=1000, convergence_threshold=1e-3,
   def fit(self, X, y, random_state=np.random):
     """Create constraints from labels and learn the ITML model.
 
+
     Parameters
     ----------
     X : (n x d) matrix

metric_learn/lfda.py

@@ -25,7 +25,13 @@ class LFDA(MahalanobisMixin, TransformerMixin):
   '''
   Local Fisher Discriminant Analysis for Supervised Dimensionality Reduction
   Sugiyama, ICML 2006
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
   '''
+
   def __init__(self, num_dims=None, k=None, embedding_type='weighted'):
     '''
     Initialize LFDA.

metric_learn/lmnn.py

@@ -243,6 +243,13 @@ def _sum_outer_products(data, a_inds, b_inds, weights=None):
   from modshogun import RealFeatures, MulticlassLabels
 
   class LMNN(_base_LMNN):
+    """Large Margin Nearest Neighbor (LMNN)
+
+    Attributes
+    ----------
+    transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+        The learned linear transformation ``L``.
+    """
 
     def fit(self, X, y):
       self.X_, y = check_X_y(X, y, dtype=float)

metric_learn/lsml.py

@@ -99,7 +99,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):
@@ -129,6 +129,14 @@ def _gradient(self, metric):
 
 
 class LSML(_BaseLSML, _QuadrupletsClassifierMixin):
+  """Least Squared-residual Metric Learning (LSML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
 
   def fit(self, quadruplets, weights=None):
     """Learn the LSML model.
@@ -152,6 +160,15 @@ def fit(self, quadruplets, weights=None):
 
 
 class LSML_Supervised(_BaseLSML, TransformerMixin):
+  """Supervised version of Least Squared-residual Metric Learning (LSML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
+
   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

@@ -21,7 +21,14 @@
 
 
 class MLKR(MahalanobisMixin, TransformerMixin):
-  """Metric Learning for Kernel Regression (MLKR)"""
+  """Metric Learning for Kernel Regression (MLKR)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
+  """
+
   def __init__(self, num_dims=None, A0=None, epsilon=0.01, alpha=0.0001,
                max_iter=1000):
     """

metric_learn/mmc.py

@@ -217,7 +217,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):
@@ -277,7 +277,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):
@@ -359,6 +359,14 @@ def _D_constraint(self, neg_pairs, w):
 
 
 class MMC(_BaseMMC, _PairsClassifierMixin):
+  """Mahalanobis Metric for Clustering (MMC)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
 
   def fit(self, pairs, y):
     """Learn the MMC model.
@@ -379,7 +387,15 @@ def fit(self, pairs, y):
 
 
 class MMC_Supervised(_BaseMMC, TransformerMixin):
-  """Mahalanobis Metric for Clustering (MMC)"""
+  """Supervised version of Mahalanobis Metric for Clustering (MMC)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
+
   def __init__(self, max_iter=100, max_proj=10000, convergence_threshold=1e-6,
                num_labeled=np.inf, num_constraints=None,
                A0=None, diagonal=False, diagonal_c=1.0, verbose=False):

metric_learn/nca.py

@@ -15,6 +15,14 @@
 
 
 class NCA(MahalanobisMixin, TransformerMixin):
+  """Neighborhood Components Analysis (NCA)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
+  """
+
   def __init__(self, num_dims=None, max_iter=100, learning_rate=0.01):
     self.num_dims = num_dims
     self.max_iter = max_iter

metric_learn/rca.py

@@ -37,7 +37,14 @@ def _chunk_mean_centering(data, chunks):
 
 
 class RCA(MahalanobisMixin, TransformerMixin):
-  """Relevant Components Analysis (RCA)"""
+  """Relevant Components Analysis (RCA)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
+  """
+
   def __init__(self, num_dims=None, pca_comps=None):
     """Initialize the learner.
 
@@ -134,6 +141,14 @@ def _inv_sqrtm(x):
 
 
 class RCA_Supervised(RCA):
+  """Supervised version of Relevant Components Analysis (RCA)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The learned linear transformation ``L``.
+  """
+
   def __init__(self, num_dims=None, pca_comps=None, num_chunks=100,
                chunk_size=2):
     """Initialize the learner.

metric_learn/sdml.py

@@ -67,11 +67,19 @@ def _fit(self, pairs, y):
     emp_cov = emp_cov.T.dot(emp_cov)
     _, self.M_ = graph_lasso(emp_cov, self.sparsity_param, verbose=self.verbose)
 
-    self.transformer_ = self._transformer_from_metric(self.M_)
+    self.transformer_ = self.transformer_from_metric(self.M_)
     return self
 
 
 class SDML(_BaseSDML, _PairsClassifierMixin):
+  """Sparse Distance Metric Learning (SDML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
 
   def fit(self, pairs, y):
     """Learn the SDML model.
@@ -92,6 +100,15 @@ def fit(self, pairs, y):
 
 
 class SDML_Supervised(_BaseSDML, TransformerMixin):
+  """Supervised version of Sparse Distance Metric Learning (SDML)
+
+  Attributes
+  ----------
+  transformer_ : `numpy.ndarray`, shape=(num_dims, n_features)
+      The linear transformation ``L`` deduced from the learned Mahalanobis
+      metric (See :meth:`transformer_from_metric`.)
+  """
+
   def __init__(self, balance_param=0.5, sparsity_param=0.01, use_cov=True,
                num_labeled=np.inf, num_constraints=None, verbose=False):
     """