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

* add docstrings for constraints class, pairs and chunks methods

* fix missing optional values and descriptions, uniformize

* fix indentation problems in docstring and uniformize

Author: bellet

metric_learn/_util.py

@@ -448,45 +448,45 @@ def _initialize_components(n_components, input, y=None, init='auto',
     The input labels (or not if there are no labels).
 
   init : string or numpy array, optional (default='auto')
-      Initialization of the linear transformation. Possible options are
-      'auto', 'pca', 'lda', 'identity', 'random', and a numpy array of shape
-      (n_features_a, n_features_b).
-
-      'auto'
-          Depending on ``n_components``, the most reasonable initialization
-          will be chosen. If ``n_components <= n_classes`` we use 'lda' (see
-          the description of 'lda' init), as it uses labels information. If
-          not, but ``n_components < min(n_features, n_samples)``, we use 'pca',
-          as it projects data onto meaningful directions (those of higher
-          variance). Otherwise, we just use 'identity'.
-
-      'pca'
-          ``n_components`` principal components of the inputs passed
-          to :meth:`fit` will be used to initialize the transformation.
-          (See `sklearn.decomposition.PCA`)
-
-      'lda'
-          ``min(n_components, n_classes)`` most discriminative
-          components of the inputs passed to :meth:`fit` will be used to
-          initialize the transformation. (If ``n_components > n_classes``,
-          the rest of the components will be zero.) (See
-          `sklearn.discriminant_analysis.LinearDiscriminantAnalysis`).
-          This initialization is possible only if `has_classes == True`.
-
-      'identity'
-          The identity matrix. If ``n_components`` is strictly smaller than the
-          dimensionality of the inputs passed to :meth:`fit`, the identity
-          matrix will be truncated to the first ``n_components`` rows.
-
-      'random'
-          The initial transformation will be a random array of shape
-          `(n_components, n_features)`. Each value is sampled from the
-          standard normal distribution.
-
-      numpy array
-          n_features_b must match the dimensionality of the inputs passed to
-          :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.
+    Initialization of the linear transformation. Possible options are
+    'auto', 'pca', 'lda', 'identity', 'random', and a numpy array of shape
+    (n_features_a, n_features_b).
+
+    'auto'
+      Depending on ``n_components``, the most reasonable initialization
+      will be chosen. If ``n_components <= n_classes`` we use 'lda' (see
+      the description of 'lda' init), as it uses labels information. If
+      not, but ``n_components < min(n_features, n_samples)``, we use 'pca',
+      as it projects data onto meaningful directions (those of higher
+      variance). Otherwise, we just use 'identity'.
+
+    'pca'
+      ``n_components`` principal components of the inputs passed
+      to :meth:`fit` will be used to initialize the transformation.
+      (See `sklearn.decomposition.PCA`)
+
+    'lda'
+      ``min(n_components, n_classes)`` most discriminative
+      components of the inputs passed to :meth:`fit` will be used to
+      initialize the transformation. (If ``n_components > n_classes``,
+      the rest of the components will be zero.) (See
+      `sklearn.discriminant_analysis.LinearDiscriminantAnalysis`).
+      This initialization is possible only if `has_classes == True`.
+
+    'identity'
+      The identity matrix. If ``n_components`` is strictly smaller than the
+      dimensionality of the inputs passed to :meth:`fit`, the identity
+      matrix will be truncated to the first ``n_components`` rows.
+
+    'random'
+      The initial transformation will be a random array of shape
+      `(n_components, n_features)`. Each value is sampled from the
+      standard normal distribution.
+
+    numpy array
+      n_features_b must match the dimensionality of the inputs passed to
+      :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.
 
   verbose : bool
     Whether to print the details of the initialization or not.
@@ -606,26 +606,26 @@ def _initialize_metric_mahalanobis(input, init='identity', random_state=None,
     The input samples (can be tuples or regular samples).
 
   init : string or numpy array, optional (default='identity')
-         Specification for the matrix to initialize. Possible options are
-         'identity', 'covariance', 'random', and a numpy array of shape
-         (n_features, n_features).
-
-         'identity'
-            An identity matrix of shape (n_features, n_features).
-
-         'covariance'
-            The (pseudo-)inverse covariance matrix (raises an error if the
-            covariance matrix is not definite and `strict_pd == True`)
-
-         'random'
-             A random positive definite (PD) matrix of shape
-             `(n_features, n_features)`, generated using
-             `sklearn.datasets.make_spd_matrix`.
-
-         numpy array
-             A PSD matrix (or strictly PD if strict_pd==True) of
-             shape (n_features, n_features), that will be used as such to
-             initialize the metric, or set the prior.
+    Specification for the matrix to initialize. Possible options are
+    'identity', 'covariance', 'random', and a numpy array of shape
+    (n_features, n_features).
+
+    'identity'
+      An identity matrix of shape (n_features, n_features).
+
+    'covariance'
+      The (pseudo-)inverse covariance matrix (raises an error if the
+      covariance matrix is not definite and `strict_pd == True`)
+
+    'random'
+      A random positive definite (PD) matrix of shape
+      `(n_features, n_features)`, generated using
+      `sklearn.datasets.make_spd_matrix`.
+
+    numpy array
+      A PSD matrix (or strictly PD if strict_pd==True) of
+      shape (n_features, n_features), that will be used as such to
+      initialize the metric, or set the prior.
 
   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

metric_learn/base_metric.py

@@ -154,12 +154,12 @@ def transform(self, X):
     Parameters
     ----------
     X : (n x d) matrix
-        Data to transform.
+      Data to transform.
 
     Returns
     -------
     transformed : (n x d) matrix
-        Input data transformed to the metric space by :math:`XL^{\\top}`
+      Input data transformed to the metric space by :math:`XL^{\\top}`
     """
 
 
@@ -180,7 +180,7 @@ class MahalanobisMixin(six.with_metaclass(ABCMeta, BaseMetricLearner,
   Attributes
   ----------
   components_ : `numpy.ndarray`, shape=(n_components, n_features)
-      The learned linear transformation ``L``.
+    The learned linear transformation ``L``.
   """
 
   def score_pairs(self, pairs):
@@ -313,9 +313,9 @@ class _PairsClassifierMixin(BaseMetricLearner):
   Attributes
   ----------
   threshold_ : `float`
-      If the distance metric between two points is lower than this threshold,
-      points will be classified as similar, otherwise they will be
-      classified as dissimilar.
+    If the distance metric between two points is lower than this threshold,
+    points will be classified as similar, otherwise they will be
+    classified as dissimilar.
   """
 
   _tuple_size = 2  # number of points in a tuple, 2 for pairs

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,30 @@ 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)