Add documentation for the new API (#133)

wdevazelhes · perimosocordiae · commit 073451adf218 · 2018-12-20T12:38:01.000-05:00
* Create some text to initialize the PR * DOC: add doc outline * DOC: Add data visualisation to possible examples * Update documentation outline * Add doc from master * DOC: add beginning of doc tree * DOC: add some beginning of example to get started with the examples section using sphinx-gallery * DOC: modify gitignore to ignore auto_examples * WIP: add preprocessor section and some section about weakly supervised learners and copy the previous content to the different sections * A few style improvements (text wraping to line limit, better references formatting ...) * Address #133 (review) * raise instead of return * Fix quickstart example * Emphasize scikit-learn compatibility * Update introduction with new methods * address #133 (comment) * explain what happens when preprocessor=None * Precisions in doc about the input accepted by the preprocessor * address #133 (comment) * Better formulation of sentences * change title formatting in index * Fix references and some numering issue * Reformat link to preprocessor * Fix automatic link to algorithms for the supervised section * Reformatting and adding examples about supervised version in the end of the weakly supervised version * add precisions in the intro * add precisions for score_pairs in the intro * Change examples for weakly supervised section * add _Supervised section in Supervised section * change examples in weakly supervised section * fix empty module contents * rename sandwich.py into plot_sandwich.py to be found by sphinx-gallery
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@ dist/
 .coverage
 htmlcov/
 .cache/
+doc/auto_examples/*
diff --git a/doc/conf.py b/doc/conf.py
@@ -7,6 +7,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
     'numpydoc',
+    'sphinx_gallery.gen_gallery'
 ]
 
 templates_path = ['_templates']
@@ -15,7 +16,7 @@
 
 # General information about the project.
 project = u'metric-learn'
-copyright = u'2015-2017, CJ Carey and Yuan Tang'
+copyright = u'2015-2018, CJ Carey and Yuan Tang'
 author = u'CJ Carey and Yuan Tang'
 version = '0.4.0'
 release = '0.4.0'
@@ -31,3 +32,6 @@
 html_static_path = ['_static']
 htmlhelp_basename = 'metric-learndoc'
 
+# Option to only need single backticks to refer to symbols
+default_role = 'any'
+
diff --git a/doc/getting_started.rst b/doc/getting_started.rst
@@ -0,0 +1,42 @@
+###############
+Getting started
+###############
+
+Installation and Setup
+======================
+
+Run ``pip install metric-learn`` to download and install from PyPI.
+
+Alternately, download the source repository and run:
+
+-  ``python setup.py install`` for default installation.
+-  ``python setup.py test`` to run all tests.
+
+**Dependencies**
+
+-  Python 2.7+, 3.4+
+-  numpy, scipy, scikit-learn
+-  (for running the examples only: matplotlib)
+
+**Notes**
+
+If a recent version of the Shogun Python modular (``modshogun``) library
+is available, the LMNN implementation will use the fast C++ version from
+there. The two implementations differ slightly, and the C++ version is
+more complete.
+
+
+Quick start
+===========
+
+This example loads the iris dataset, and evaluates a k-nearest neighbors
+algorithm on an embedding space learned with `NCA`.
+
+>>> from metric_learn import NCA
+>>> from sklearn.datasets import load_iris
+>>> from sklearn.model_selection import cross_val_score
+>>> from sklearn.pipeline import make_pipeline
+>>>
+>>> X, y = load_iris(return_X_y=True)
+>>> clf = make_pipeline(NCA(), KNeighborsClassifier())
+>>> cross_val_score(clf, X, y)
diff --git a/doc/index.rst b/doc/index.rst
@@ -2,78 +2,31 @@ metric-learn: Metric Learning in Python
 =======================================
 |License| |PyPI version|
 
-Distance metrics are widely used in the machine learning literature.
-Traditionally, practicioners would choose a standard distance metric
-(Euclidean, City-Block, Cosine, etc.) using a priori knowledge of
-the domain.
-Distance metric learning (or simply, metric learning) is the sub-field of
-machine learning dedicated to automatically constructing optimal distance
-metrics.
-
-This package contains efficient Python implementations of several popular
-metric learning algorithms.
+Welcome to metric-learn's documentation !
+-----------------------------------------
 
 .. 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.rca
-
-Each metric supports the following methods:
-
--  ``fit(...)``, which learns the model.
--  ``transformer()``, which returns a transformation matrix
-   :math:`L \in \mathbb{R}^{D \times d}`, which can be used to convert a
-   data matrix :math:`X \in \mathbb{R}^{n \times d}` to the
-   :math:`D`-dimensional learned metric space :math:`X L^{\top}`,
-   in which standard Euclidean distances may be used.
--  ``transform(X)``, which applies the aforementioned transformation.
--  ``metric()``, which returns a Mahalanobis matrix
-   :math:`M = L^{\top}L` such that distance between vectors ``x`` and
-   ``y`` can be computed as :math:`\left(x-y\right)M\left(x-y\right)`.
+   :maxdepth: 2
 
+   getting_started
 
-Installation and Setup
-======================
-
-Run ``pip install metric-learn`` to download and install from PyPI.
-
-Alternately, download the source repository and run:
-
--  ``python setup.py install`` for default installation.
--  ``python setup.py test`` to run all tests.
+.. toctree::
+   :maxdepth: 2
 
-**Dependencies**
+   user_guide
 
--  Python 2.7+, 3.4+
--  numpy, scipy, scikit-learn
--  (for running the examples only: matplotlib)
+.. toctree::
+   :maxdepth: 2
 
-**Notes**
+   Package Overview <metric_learn>
 
-If a recent version of the Shogun Python modular (``modshogun``) library
-is available, the LMNN implementation will use the fast C++ version from
-there. The two implementations differ slightly, and the C++ version is
-more complete.
+.. toctree::
+   :maxdepth: 2
 
-Navigation
-----------
+   auto_examples/index
 
 :ref:`genindex` | :ref:`modindex` | :ref:`search`
 
-.. toctree::
-   :maxdepth: 4
-   :hidden:
-
-   Package Overview <metric_learn>
-
 .. |PyPI version| image:: https://badge.fury.io/py/metric-learn.svg
    :target: http://badge.fury.io/py/metric-learn
 .. |License| image:: http://img.shields.io/:license-mit-blue.svg?style=flat
diff --git a/doc/introduction.rst b/doc/introduction.rst
@@ -0,0 +1,38 @@
+============
+Introduction
+============
+
+Distance metrics are widely used in the machine learning literature.
+Traditionally, practitioners would choose a standard distance metric
+(Euclidean, City-Block, Cosine, etc.) using a priori knowledge of
+the domain.
+Distance metric learning (or simply, metric learning) is the sub-field of
+machine learning dedicated to automatically construct task-specific distance
+metrics from (weakly) supervised data.
+The learned distance metric often corresponds to a Euclidean distance in a new
+embedding space, hence distance metric learning can be seen as a form of
+representation learning.
+
+This package contains a efficient Python implementations of several popular
+metric learning algorithms, compatible with scikit-learn. This allows to use
+all the scikit-learn routines for pipelining and model selection for
+metric learning algorithms.
+
+
+Currently, each metric learning algorithm supports the following methods:
+
+-  ``fit(...)``, which learns the model.
+-  ``metric()``, which returns a Mahalanobis matrix
+   :math:`M = L^{\top}L` such that distance between vectors ``x`` and
+   ``y`` can be computed as :math:`\left(x-y\right)M\left(x-y\right)`.
+-  ``transformer_from_metric(metric)``, which returns a transformation matrix
+   :math:`L \in \mathbb{R}^{D \times d}`, which can be used to convert a
+   data matrix :math:`X \in \mathbb{R}^{n \times d}` to the
+   :math:`D`-dimensional learned metric space :math:`X L^{\top}`,
+   in which standard Euclidean distances may be used.
+-  ``transform(X)``, which applies the aforementioned transformation.
+- ``score_pairs(pairs)`` which returns the distance between pairs of
+  points. ``pairs`` should be a 3D array-like of pairs of shape ``(n_pairs,
+  2, n_features)``, or it can be a 2D array-like of pairs indicators of
+  shape ``(n_pairs, 2)`` (see section :ref:`preprocessor_section` for more
+  details).
diff --git a/doc/metric_learn.covariance.rst b/doc/metric_learn.covariance.rst
@@ -6,6 +6,7 @@ Covariance metric (baseline method)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------
diff --git a/doc/metric_learn.itml.rst b/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
 ------------
diff --git a/doc/metric_learn.lfda.rst b/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
 ------------
diff --git a/doc/metric_learn.lmnn.rst b/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
 ------------
diff --git a/doc/metric_learn.lsml.rst b/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
 ------------
diff --git a/doc/metric_learn.mlkr.rst b/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
 ------------
diff --git a/doc/metric_learn.mmc.rst b/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
 ------------
diff --git a/doc/metric_learn.nca.rst b/doc/metric_learn.nca.rst
@@ -6,6 +6,7 @@ Neighborhood Components Analysis (NCA)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------
diff --git a/doc/metric_learn.rca.rst b/doc/metric_learn.rca.rst
@@ -6,6 +6,7 @@ Relative Components Analysis (RCA)
     :undoc-members:
     :inherited-members:
     :show-inheritance:
+    :special-members: __init__
 
 Example Code
 ------------
diff --git a/doc/metric_learn.rst b/doc/metric_learn.rst
@@ -1,8 +1,8 @@
 metric_learn package
 ====================
 
-Submodules
-----------
+Module Contents
+---------------
 
 .. toctree::
 
@@ -16,11 +16,3 @@ Submodules
    metric_learn.nca
    metric_learn.rca
    metric_learn.sdml
-
-Module contents
----------------
-
-.. automodule:: metric_learn
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/doc/metric_learn.sdml.rst b/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
 ------------
diff --git a/doc/preprocessor.rst b/doc/preprocessor.rst
diff --git a/doc/supervised.rst b/doc/supervised.rst
diff --git a/doc/user_guide.rst b/doc/user_guide.rst
diff --git a/doc/weakly_supervised.rst b/doc/weakly_supervised.rst
diff --git a/examples/README.txt b/examples/README.txt
diff --git a/examples/plot_sandwich.py b/examples/plot_sandwich.py
