[MRG] Improve docstrings: add them for Constraints class and methods and fix minor problems

metric_learn/constraints.py

@@ -12,17 +12,60 @@
 
 class Constraints(object):
   """
-  Class to build constraints from labels.
+  Class to build constraints from labeled data.
 
-  See more in the :ref:`User Guide <supervised_version>`
+  See more in the :ref:`User Guide <supervised_version>`.
+
+  Parameters
+  ----------
+  partial_labels : `numpy.ndarray` of ints, shape=(n_samples,)
+      Array of labels, with -1 indicating unknown label.
+
+  Attributes
+  ----------
+  partial_labels : `numpy.ndarray` of ints, shape=(n_samples,)
+      Array of labels, with -1 indicating unknown label.
   """
+
   def __init__(self, partial_labels):
-    '''partial_labels : int arraylike, -1 indicating unknown label'''
     partial_labels = np.asanyarray(partial_labels, dtype=int)
     self.partial_labels = partial_labels
 
   def positive_negative_pairs(self, num_constraints, same_length=False,
                               random_state=None):
+    """
+    Generates positive pairs and negative pairs from labeled data.
+
+    Positive pairs are formed by randomly drawing ``num_constraints`` pairs of
+    points with the same label. Negative pairs are formed by randomly drawing
+    ``num_constraints`` pairs of points with different label.
+
+    In the case where it is not possible to generate enough positive or
+    negative pairs, a smaller number of pairs will be returned with a warning.
+
+    Parameters
+    ----------
+      num_constraints : int
+        Number of positive and negative constraints to generate.
+      same_length : bool, optional (default=False)
+        If True, forces the number of positive and negative pairs to be
+        equal by ignoring some pairs from the larger set.
+      random_state : int or numpy.RandomState or None, optional (default=None)
+        A pseudo random number generator object or a seed for it if int.
+    Returns
+    -------
+    a : array-like, shape=(n_constraints,)
+    1D array of indicators for the left elements of positive pairs.
+
+    b : array-like, shape=(n_constraints,)
+    1D array of indicators for the right elements of positive pairs.
+
+    c : array-like, shape=(n_constraints,)
+    1D array of indicators for the left elements of negative pairs.
+
+    d : array-like, shape=(n_constraints,)
+    1D array of indicators for the right elements of negative pairs.
+    """
     random_state = check_random_state(random_state)
     a, b = self._pairs(num_constraints, same_label=True,
                        random_state=random_state)
@@ -60,7 +103,27 @@ def _pairs(self, num_constraints, same_label=True, max_iter=10,
 
   def chunks(self, num_chunks=100, chunk_size=2, random_state=None):
     """
-    the random state object to be passed must be a numpy random seed
+    Generates chunks from labeled data.
+
+    Each of ``num_chunks`` chunks is composed of ``chunk_size`` points from
+    the same class drawn at random. Each point can belong to at most 1 chunk.
+
+    In the case where there is not enough points to generate ``num_chunks``
+    chunks of size ``chunk_size``, a ValueError will be raised.
+
+    Parameters
+    ----------
+      num_chunks : int, optional (default=100)
+        Number of chunks to generate.
+      chunk_size : int, optional (default=2)
+        Number of points in each chunk.
+      random_state : int or numpy.RandomState or None, optional (default=None)
+        A pseudo random number generator object or a seed for it if int.
+    Returns
+    -------
+    chunks : array-like, shape=(n_samples,)
+    1D array of chunk indicators, where -1 indicates that the point does not
+    belong to any chunk.
     """
     random_state = check_random_state(random_state)
     chunks = -np.ones_like(self.partial_labels, dtype=int)

metric_learn/itml.py

@@ -126,7 +126,7 @@ class ITML(_BaseITML, _PairsClassifierMixin):
 
   Parameters
   ----------
-  gamma : float, optional (default=1.)
+  gamma : float, optional (default=1.0)
       Value for slack variables
 
   max_iter : int, optional (default=1000)
@@ -266,17 +266,24 @@ class ITML_Supervised(_BaseITML, TransformerMixin):
 
   Parameters
   ----------
-  gamma : float, optional
-      value for slack variables
-  max_iter : int, optional
-  convergence_threshold : float, optional
+  gamma : float, optional (default=1.0)
+      Value for slack variables
+
+  max_iter : int, optional (default=1000)
+      Maximum number of iterations of the optimization procedure.
+
+  convergence_threshold : float, optional (default=1e-3)
+      Tolerance of the optimization procedure.
+
   num_labeled : Not used
         .. deprecated:: 0.5.0
            `num_labeled` was deprecated in version 0.5.0 and will
            be removed in 0.6.0.
-  num_constraints: int, optional
-      number of constraints to generate
-      (`20 * num_classes**2` constraints by default)
+
+  num_constraints: int, optional (default=None)
+      Number of constraints to generate. If None, default to `20 *
+      num_classes**2`.
+
   bounds : Not used
          .. deprecated:: 0.5.0
         `bounds` was deprecated in version 0.5.0 and will
@@ -304,15 +311,19 @@ class ITML_Supervised(_BaseITML, TransformerMixin):
            A positive definite (PD) matrix of shape
            (n_features, n_features), that will be used as such to set the
            prior.
+
   A0 : Not used
     .. deprecated:: 0.5.0
        `A0` was deprecated in version 0.5.0 and will
        be removed in 0.6.0. Use 'prior' instead.
-  verbose : bool, optional
-      if True, prints information while learning
+
+  verbose : bool, optional (default=False)
+      If True, prints information while learning
+
   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].
+
   random_state : int or numpy.RandomState or None, optional (default=None)
       A pseudo random number generator object or a seed for it if int. If
       ``prior='random'``, ``random_state`` is used to set the prior. In any
@@ -355,7 +366,7 @@ class ITML_Supervised(_BaseITML, TransformerMixin):
     that describes the supervised version of weakly supervised estimators.
   """
 
-  def __init__(self, gamma=1., max_iter=1000, convergence_threshold=1e-3,
+  def __init__(self, gamma=1.0, max_iter=1000, convergence_threshold=1e-3,
                num_labeled='deprecated', num_constraints=None,
                bounds='deprecated', prior='identity', A0='deprecated',
                verbose=False, preprocessor=None, random_state=None):

metric_learn/lfda.py

@@ -35,12 +35,12 @@ class LFDA(MahalanobisMixin, TransformerMixin):
         `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, n_components - 1).
+  k : int, optional (default=None)
+      Number of nearest neighbors used in local scaling method. If None,
+      defaults to min(7, n_features - 1).
 
-  embedding_type : str, optional
-      Type of metric in the embedding space (default: 'weighted')
+  embedding_type : str, optional (default: 'weighted')
+      Type of metric in the embedding space
         'weighted'        - weighted eigenvectors
         'orthonormalized' - orthonormalized
         'plain'           - raw eigenvectors

metric_learn/lmnn.py

@@ -31,8 +31,8 @@ class LMNN(MahalanobisMixin, TransformerMixin):
       Initialization of the linear transformation. Possible options are
       'auto', 'pca', 'identity', 'random', and a numpy array of shape
       (n_features_a, n_features_b). If None, will be set automatically to
-        'auto' (this option is to raise a warning if 'init' is not set,
-        and stays to its default value None, in v0.5.0).
+      'auto' (this option is to raise a warning if 'init' is not set, and
+      stays to its default value None, in v0.5.0).
 
       'auto'
           Depending on ``n_components``, the most reasonable initialization
@@ -69,7 +69,7 @@ class LMNN(MahalanobisMixin, TransformerMixin):
           :meth:`fit` and n_features_a must be less than or equal to that.
           If ``n_components`` is not None, n_features_a must match it.
 
-  k : int, optional
+  k : int, optional (default=3)
       Number of neighbors to consider, not including self-edges.
 
   min_iter : int, optional (default=50)
@@ -94,8 +94,9 @@ class LMNN(MahalanobisMixin, TransformerMixin):
   verbose : bool, optional (default=False)
       Whether to print the progress of the optimization procedure.
 
-  regularization: float, optional
-      Weighting of pull and push terms, with 0.5 meaning equal weight.
+  regularization: float, optional (default=0.5)
+      Relative weight between pull and push terms, with 0.5 meaning equal
+      weight.
 
   preprocessor : array-like, shape=(n_samples, n_features) or callable
       The preprocessor to call to get tuples from indices. If array-like,

metric_learn/lsml.py

@@ -163,13 +163,19 @@ class LSML(_BaseLSML, _QuadrupletsClassifierMixin):
            (n_features, n_features), that will be used as such to set the
            prior.
 
-  tol : float, optional
-  max_iter : int, optional
-  verbose : bool, optional
-      if True, prints information while learning
+  tol : float, optional (default=1e-3)
+      Convergence tolerance of the optimization procedure.
+
+  max_iter : int, optional (default=1000)
+      Maximum number of iteration of the optimization procedure.
+
+  verbose : bool, optional (default=False)
+      If True, prints information while learning
+
   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].
+
   random_state : int or numpy.RandomState or None, optional (default=None)
       A pseudo random number generator object or a seed for it if int. If
       ``init='random'``, ``random_state`` is used to set the random
@@ -246,9 +252,11 @@ class LSML_Supervised(_BaseLSML, TransformerMixin):
   Parameters
   ----------
   tol : float, optional (default=1e-3)
-      Tolerance for the convergence procedure.
+      Convergence tolerance of the optimization procedure.
+
   max_iter : int, optional (default=1000)
-      Number of maximum iterations of the convergence procedure.
+      Number of maximum iterations of the optimization procedure.
+
   prior : None, string or numpy array, optional (default=None)
       Prior to set for the metric. Possible options are
       'identity', 'covariance', 'random', and a numpy array of
@@ -272,20 +280,27 @@ class LSML_Supervised(_BaseLSML, TransformerMixin):
           A positive definite (PD) matrix of shape
           (n_features, n_features), that will be used as such to set the
           prior.
+
   num_labeled : Not used
     .. deprecated:: 0.5.0
        `num_labeled` was deprecated in version 0.5.0 and will
        be removed in 0.6.0.
-  num_constraints: int, optional
-      number of constraints to generate
-      (`20 * num_classes**2` constraints by default)
-  weights : (m,) array of floats, optional
-      scale factor for each constraint
-  verbose : bool, optional
-      if True, prints information while learning
+
+  num_constraints: int, optional (default=None)
+      Number of constraints to generate. If None, default to `20 *
+      num_classes**2`.
+
+  weights : (num_constraints,) array of floats, optional (default=None)
+      Relative weight given to each constraint. If None, defaults to uniform
+      weights.
+
+  verbose : bool, optional (default=False)
+      If True, prints information while learning
+
   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].
+
   random_state : int or numpy.RandomState or None, optional (default=None)
       A pseudo random number generator object or a seed for it if int. If
       ``init='random'``, ``random_state`` is used to set the random

metric_learn/mlkr.py

@@ -82,7 +82,7 @@ class MLKR(MahalanobisMixin, TransformerMixin):
   tol: float, optional (default=None)
       Convergence tolerance for the optimization.
 
-  max_iter: int, optional
+  max_iter: int, optional (default=1000)
       Cap on number of conjugate gradient iterations.
 
   verbose : bool, optional (default=False)