[MRG] New api design (#139)

[MRG] New api design

Author: wdevazelhes

.gitignore

@@ -5,3 +5,4 @@ dist/
 .coverage
 htmlcov/
 .cache/
+doc/auto_examples/*

README.rst

@@ -34,27 +34,8 @@ package installed).
 
 **Usage**
 
-For full usage examples, see the `sphinx documentation`_.
-
-Each metric is a subclass of ``BaseMetricLearner``, which provides
-default implementations for the methods ``metric``, ``transformer``, and
-``transform``. Subclasses must provide an implementation for either
-``metric`` or ``transformer``.
-
-For an instance of a metric learner named ``foo`` learning from a set of
-``d``-dimensional points, ``foo.metric()`` returns a ``d x d``
-matrix ``M`` such that the distance between vectors ``x`` and ``y`` is
-expressed ``sqrt((x-y).dot(M).dot(x-y))``.
-Using scipy's ``pdist`` function, this would look like
-``pdist(X, metric='mahalanobis', VI=foo.metric())``.
-
-In the same scenario, ``foo.transformer()`` returns a ``d x d``
-matrix ``L`` such that a vector ``x`` can be represented in the learned
-space as the vector ``x.dot(L.T)``.
-
-For convenience, the function ``foo.transform(X)`` is provided for
-converting a matrix of points (``X``) into the learned space, in which
-standard Euclidean distance can be used.
+See the `sphinx documentation`_ for full documentation about installation, API,
+ usage, and examples.
 
 **Notes**
 

bench/benchmarks/iris.py

@@ -10,7 +10,7 @@
     'LMNN': metric_learn.LMNN(k=5, learn_rate=1e-6, verbose=False),
     'LSML_Supervised': metric_learn.LSML_Supervised(num_constraints=200),
     'MLKR': metric_learn.MLKR(),
-    'NCA': metric_learn.NCA(max_iter=700, learning_rate=0.01, num_dims=2),
+    'NCA': metric_learn.NCA(max_iter=700, num_dims=2),
     'RCA_Supervised': metric_learn.RCA_Supervised(dim=2, num_chunks=30,
                                                   chunk_size=2),
     'SDML_Supervised': metric_learn.SDML_Supervised(num_constraints=1500),

doc/conf.py

@@ -7,6 +7,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.mathjax',
     'numpydoc',
+    'sphinx_gallery.gen_gallery'
 ]
 
 templates_path = ['_templates']
@@ -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'
+

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)

doc/index.rst

@@ -2,103 +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.
-
-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.
+Welcome to metric-learn's documentation !
+-----------------------------------------
 
 .. toctree::
-   :maxdepth: 1
-
-   metric_learn.covariance
-   metric_learn.lmnn
-   metric_learn.nca
-   metric_learn.lfda
-   metric_learn.mlkr
+   :maxdepth: 2
 
-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.
+   getting_started
 
 .. toctree::
-   :maxdepth: 1
-
-   metric_learn.itml
-   metric_learn.lsml
-   metric_learn.sdml
-   metric_learn.rca
-   metric_learn.mmc
-
-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
-   :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)`.
-
-
-Installation and Setup
-======================
-
-Run ``pip install metric-learn`` to download and install from PyPI.
+   :maxdepth: 2
 
-Alternately, download the source repository and run:
+   user_guide
 
--  ``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)
+.. 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

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:`\sqrt{\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).

doc/metric_learn.nca.rst

@@ -21,7 +21,7 @@ Example Code
     X = iris_data['data']
     Y = iris_data['target']
 
-    nca = NCA(max_iter=1000, learning_rate=0.01)
+    nca = NCA(max_iter=1000)
     nca.fit(X, Y)
 
 References

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: