[MRG] Add documentation for supervised classes and add __init__ docstrings to doc (#115)

* FEAT: Add documentation for supervised classes

* Add doc for ITML, and put mlkr to the right place in index

* FIX: update doc

* FIX: add __init__ docstrings in doc

* FIX: Update doc to suit regression too

* STY: add points at end of docstrings

* MAINT: address #115 (review)

* DOC: fix semi to weakly supervised

Author: wdevazelhes

doc/index.rst

@@ -13,22 +13,45 @@ metrics.
 This package contains efficient Python implementations of several popular
 metric learning algorithms.
 
+Supervised Algorithms
+---------------------
+Supervised metric learning algorithms take as inputs points `X` and target
+labels `y`, and learn a distance matrix that make points from the same class
+(for classification) or with close target value (for regression) close to
+each other, and points from different classes or with distant target values
+far away from each other.
+
 .. toctree::
-   :caption: Algorithms
    :maxdepth: 1
 
    metric_learn.covariance
    metric_learn.lmnn
-   metric_learn.itml
-   metric_learn.sdml
-   metric_learn.lsml
    metric_learn.nca
    metric_learn.lfda
+   metric_learn.mlkr
+
+Weakly-Supervised Algorithms
+--------------------------
+Weakly supervised algorithms work on weaker information about the data points
+than supervised algorithms. Rather than labeled points, they take as input
+similarity judgments on tuples of data points, for instance pairs of similar
+and dissimilar points. Refer to the documentation of each algorithm for its
+particular form of input data.
+
+.. toctree::
+   :maxdepth: 1
+
+   metric_learn.itml
+   metric_learn.lsml
+   metric_learn.sdml
    metric_learn.rca
    metric_learn.mmc
-   metric_learn.mlkr
 
-Each metric supports the following methods:
+Note that each weakly-supervised algorithm has a supervised version of the form
+`*_Supervised` where similarity constraints are generated from
+the labels information and passed to the underlying algorithm.
+
+Each metric learning algorithm supports the following methods:
 
 -  ``fit(...)``, which learns the model.
 -  ``transformer()``, which returns a transformation matrix

doc/metric_learn.covariance.rst

@@ -6,6 +6,7 @@ Covariance metric (baseline method)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.itml.rst

@@ -6,6 +6,7 @@ Information Theoretic Metric Learning (ITML)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.lfda.rst

@@ -6,6 +6,7 @@ Local Fisher Discriminant Analysis (LFDA)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.lmnn.rst

@@ -6,6 +6,7 @@ Large Margin Nearest Neighbor (LMNN)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.lsml.rst

@@ -6,6 +6,7 @@ Least Squares Metric Learning (LSML)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.mlkr.rst

@@ -6,6 +6,7 @@ Metric Learning for Kernel Regression (MLKR)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.mmc.rst

@@ -6,6 +6,7 @@ Mahalanobis Metric Learning for Clustering (MMC)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.nca.rst

@@ -6,6 +6,7 @@ Neighborhood Components Analysis (NCA)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.rca.rst

@@ -6,6 +6,7 @@ Relative Components Analysis (RCA)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

doc/metric_learn.sdml.rst

@@ -6,6 +6,7 @@ Sparse Determinant Metric Learning (SDML)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------

metric_learn/itml.py

@@ -145,16 +145,22 @@ class ITML_Supervised(ITML):
   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):
-    """Initialize the learner.
+    """Initialize the supervised version of `ITML`.
+
+    `ITML_Supervised` creates pairs of similar sample by taking same class
+    samples, and pairs of dissimilar samples by taking different class
+    samples. It then passes these pairs to `ITML` for training.
 
     Parameters
     ----------
     gamma : float, optional
         value for slack variables
     max_iter : int, optional
     convergence_threshold : float, optional
-    num_labeled : int, optional
-        number of labels to preserve for training
+    num_labeled : int, optional (default=np.inf)
+        number of labeled points to keep for building pairs. Extra
+        labeled points will be considered unlabeled, and ignored as such.
+        Use np.inf (default) to use all labeled points.
     num_constraints: int, optional
         number of constraints to generate
     bounds : list (pos,neg) pairs, optional

metric_learn/lsml.py

@@ -134,16 +134,23 @@ def _gradient(self, metric):
 class LSML_Supervised(LSML):
   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.
+    """Initialize the supervised version of `LSML`.
+
+    `LSML_Supervised` creates quadruplets from labeled samples by taking two
+    samples from the same class, and two samples from different classes.
+    This way it builds quadruplets where the two first points must be more
+    similar than the two last points.
 
     Parameters
     ----------
     tol : float, optional
     max_iter : int, optional
     prior : (d x d) matrix, optional
         guess at a metric [default: covariance(X)]
-    num_labeled : int, optional
-        number of labels to preserve for training
+    num_labeled : int, optional (default=np.inf)
+        number of labeled points to keep for building quadruplets. Extra
+        labeled points will be considered unlabeled, and ignored as such.
+        Use np.inf (default) to use all labeled points.
     num_constraints: int, optional
         number of constraints to generate
     weights : (m,) array of floats, optional

metric_learn/mmc.py

@@ -386,15 +386,21 @@ class MMC_Supervised(MMC):
   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):
-    """Initialize the learner.
+    """Initialize the supervised version of `MMC`.
+
+    `MMC_Supervised` creates pairs of similar sample by taking same class
+    samples, and pairs of dissimilar samples by taking different class
+    samples. It then passes these pairs to `MMC` for training.
 
     Parameters
     ----------
     max_iter : int, optional
     max_proj : int, optional
     convergence_threshold : float, optional
-    num_labeled : int, optional
-        number of labels to preserve for training
+    num_labeled : int, optional (default=np.inf)
+        number of labeled points to keep for building pairs. Extra
+        labeled points will be considered unlabeled, and ignored as such.
+        Use np.inf (default) to use all labeled points.
     num_constraints: int, optional
         number of constraints to generate
     A0 : (d x d) matrix, optional

metric_learn/rca.py

@@ -138,7 +138,11 @@ def _inv_sqrtm(x):
 class RCA_Supervised(RCA):
   def __init__(self, num_dims=None, pca_comps=None, num_chunks=100,
                chunk_size=2):
-    """Initialize the learner.
+    """Initialize the supervised version of `RCA`.
+
+    `RCA_Supervised` creates chunks of similar points by first sampling a
+    class, taking `chunk_size` elements in it, and repeating the process
+    `num_chunks` times.
 
     Parameters
     ----------

metric_learn/sdml.py

@@ -83,7 +83,12 @@ def fit(self, X, W):
 class SDML_Supervised(SDML):
   def __init__(self, balance_param=0.5, sparsity_param=0.01, use_cov=True,
                num_labeled=np.inf, num_constraints=None, verbose=False):
-    """
+    """Initialize the supervised version of `SDML`.
+
+    `SDML_Supervised` creates pairs of similar sample by taking same class
+    samples, and pairs of dissimilar samples by taking different class
+    samples. It then passes these pairs to `SDML` for training.
+
     Parameters
     ----------
     balance_param : float, optional
@@ -92,8 +97,10 @@ def __init__(self, balance_param=0.5, sparsity_param=0.01, use_cov=True,
         trade off between optimizer and sparseness (see graph_lasso)
     use_cov : bool, optional
         controls prior matrix, will use the identity if use_cov=False
-    num_labeled : int, optional
-        number of labels to preserve for training
+    num_labeled : int, optional (default=np.inf)
+        number of labeled points to keep for building pairs. Extra
+        labeled points will be considered unlabeled, and ignored as such.
+        Use np.inf (default) to use all labeled points.
     num_constraints : int, optional
         number of constraints to generate
     verbose : bool, optional