Skip to content

Commit d8726d3

Browse files
perimosocordiaeperimosocordiae
committed
Re-made docs hierarchy using sphinx-apidoc
This is a bit of a massive change, sorry! I moved all of the method descriptions to docstrings in the code, then made it so those get pulled into the generated docs. I also merged the intro with the index, so the landing page should be pretty nice to look at. Finally, I started working on converting the docstrings to numpydoc format
1 parent 7707e6e commit d8726d3

34 files changed

+579
-676
lines changed

‎doc/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎doc/Makefile

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
SPHINXOPTS =
66
SPHINXBUILD = sphinx-build
77
PAPER =
8-
BUILDDIR = build
8+
BUILDDIR = _build
99

1010
# User-friendly check for sphinx-build
1111
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -15,9 +15,9 @@ endif
1515
# Internal variables.
1616
PAPEROPT_a4 = -D latex_paper_size=a4
1717
PAPEROPT_letter = -D latex_paper_size=letter
18-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
18+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
1919
# the i18n builder cannot share the environment and doctrees with the others
20-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
20+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
2121

2222
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
2323

‎doc/_static/.gitignore

Whitespace-only changes.

‎doc/_templates/.gitignore

Whitespace-only changes.

‎doc/conf.py

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# -*- coding: utf-8 -*-
2+
3+
extensions = [
4+
'sphinx.ext.autodoc',
5+
'sphinx.ext.autosummary',
6+
'sphinx.ext.todo',
7+
'sphinx.ext.viewcode',
8+
'sphinx.ext.mathjax',
9+
'numpydoc',
10+
]
11+
12+
templates_path = ['_templates']
13+
source_suffix = '.rst'
14+
master_doc = 'index'
15+
16+
# General information about the project.
17+
project = u'metric-learn'
18+
copyright = u'2015, CJ Carey and Yuan Tang'
19+
author = u'CJ Carey and Yuan Tang'
20+
version = '0.1.0'
21+
release = '0.1.0'
22+
language = 'en'
23+
24+
exclude_patterns = ['_build']
25+
pygments_style = 'sphinx'
26+
todo_include_todos = True
27+
numpydoc_show_class_members = False
28+
29+
# Options for HTML output
30+
html_theme = 'sphinx_rtd_theme'
31+
html_static_path = ['_static']
32+
htmlhelp_basename = 'metric-learndoc'
33+

‎doc/index.rst

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
metric-learn: Metric Learning in Python
2+
=======================================
3+
|License| |PyPI version|
4+
5+
Distance metrics are widely used in the machine learning literature.
6+
Traditionally, practicioners would choose a standard distance metric
7+
(Euclidean, City-Block, Cosine, etc.) using a priori knowledge of
8+
the domain.
9+
Distance metric learning (or simply, metric learning) is the sub-field of
10+
machine learning dedicated to automatically constructing optimal distance
11+
metrics.
12+
13+
This package contains efficient Python implementations of several popular
14+
metric learning algorithms.
15+
16+
.. toctree::
17+
:caption: Algorithms
18+
:maxdepth: 1
19+
20+
metric_learn.lmnn
21+
metric_learn.itml
22+
metric_learn.sdml
23+
metric_learn.lsml
24+
metric_learn.nca
25+
metric_learn.lfda
26+
metric_learn.rca
27+
28+
Each metric supports the following methods:
29+
30+
- ``fit(...)``, which learns the model.
31+
- ``transformer()``, which returns a transformation matrix
32+
:math:`L \in \mathbb{R}^{D \times d}`, which can be used to convert a
33+
data matrix :math:`X \in \mathbb{R}^{n \times d}` to the
34+
:math:`D`-dimensional learned metric space :math:`X L^{\top}`,
35+
in which standard Euclidean distances may be used.
36+
- ``transform(X)``, which applies the aforementioned transformation.
37+
- ``metric()``, which returns a Mahalanobis matrix
38+
:math:`M = L^{\top}L` such that distance between vectors ``x`` and
39+
``y`` can be computed as :math:`\left(x-y\right)M\left(x-y\right)`.
40+
41+
42+
Installation and Setup
43+
======================
44+
45+
Run ``pip install metric-learn`` to download and install from PyPI.
46+
47+
Alternately, download the source repository and run:
48+
49+
- ``python setup.py install`` for default installation.
50+
- ``python setup.py test`` to run all tests.
51+
52+
**Dependencies**
53+
54+
- Python 2.6+
55+
- numpy, scipy, scikit-learn
56+
- (for running the examples only: matplotlib)
57+
58+
**Notes**
59+
60+
If a recent version of the Shogun Python modular (``modshogun``) library
61+
is available, the LMNN implementation will use the fast C++ version from
62+
there. The two implementations differ slightly, and the C++ version is
63+
more complete.
64+
65+
Naviagtion
66+
----------
67+
68+
:ref:`genindex` | :ref:`modindex` | :ref:`search`
69+
70+
.. toctree::
71+
:maxdepth: 4
72+
:hidden:
73+
74+
Package Overview <metric_learn>
75+
76+
.. |PyPI version| image:: https://badge.fury.io/py/metric-learn.svg
77+
:target: http://badge.fury.io/py/metric-learn
78+
.. |License| image:: http://img.shields.io/:license-mit-blue.svg?style=flat
79+
:target: http://badges.mit-license.org

‎doc/make.bat

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@ REM Command file for Sphinx documentation
55
if "%SPHINXBUILD%" == "" (
66
set SPHINXBUILD=sphinx-build
77
)
8-
set BUILDDIR=build
9-
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
10-
set I18NSPHINXOPTS=%SPHINXOPTS% source
8+
set BUILDDIR=_build
9+
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
10+
set I18NSPHINXOPTS=%SPHINXOPTS% .
1111
if NOT "%PAPER%" == "" (
1212
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
1313
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%

‎doc/metric_learn.base_metric.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
metric_learn.base_metric module
2+
===============================
3+
4+
.. automodule:: metric_learn.base_metric
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎doc/metric_learn.itml.rst

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Information Theoretic Metric Learning (ITML)
2+
============================================
3+
4+
.. automodule:: metric_learn.itml
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import ITML
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
itml = ITML()
24+
25+
num_constraints = 200
26+
C = ITML.prepare_constraints(Y, X.shape[0], num_constraints)
27+
itml.fit(X, C, verbose=False)
28+
29+
References
30+
----------
31+
`Information-theoretic Metric Learning <http://machinelearning.wustl.edu/mlpapers/paper_files/icml2007_DavisKJSD07.pdf>`_ Jason V. Davis, et al.

‎doc/metric_learn.lfda.rst

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Local Fisher Discriminant Analysis (LFDA)
2+
=========================================
3+
4+
.. automodule:: metric_learn.lfda
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import LFDA
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
lfda = LFDA(k=2, dim=2)
24+
lfda.fit(X, Y)
25+
26+
References
27+
------------------
28+
`Dimensionality Reduction of Multimodal Labeled Data by Local Fisher Discriminant Analysis <http://www.ms.k.u-tokyo.ac.jp/2007/LFDA.pdf>`_ Masashi Sugiyama.
29+
30+
`Local Fisher Discriminant Analysis on Beer Style Clustering <https://gastrograph.com/resources/whitepapers/local-fisher-discriminant-analysis-on-beer-style-clustering.html#>`_ Yuan Tang.

‎doc/metric_learn.lmnn.rst

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Large Margin Nearest Neighbor (LMNN)
2+
====================================
3+
4+
.. automodule:: metric_learn.lmnn
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import LMNN
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
lmnn = LMNN(k=5, learn_rate=1e-6)
24+
lmnn.fit(X, Y, verbose=False)
25+
26+
If a recent version of the Shogun Python modular (``modshogun``) library
27+
is available, the LMNN implementation will use the fast C++ version from
28+
there. Otherwise, the included pure-Python version will be used.
29+
The two implementations differ slightly, and the C++ version is more complete.
30+
31+
References
32+
----------
33+
`Distance Metric Learning for Large Margin Nearest Neighbor Classification <http://papers.nips.cc/paper/2795-distance-metric-learning-for-large-margin-nearest-neighbor-classification>`_ Kilian Q. Weinberger, John Blitzer, Lawrence K. Saul

‎doc/metric_learn.lsml.rst

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Least Squares Metric Learning (LSML)
2+
====================================
3+
4+
.. automodule:: metric_learn.lsml
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import LSML
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
lsml = LSML()
24+
C = LSML.prepare_constraints(Y, 200)
25+
isml.fit(X, C, verbose=False)
26+
27+
References
28+
----------
29+

‎doc/metric_learn.nca.rst

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Neighborhood Components Analysis (NCA)
2+
======================================
3+
4+
.. automodule:: metric_learn.nca
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import NCA
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
nca = NCA(max_iter=1000, learning_rate=0.01)
24+
nca.fit(X, Y)
25+
26+
References
27+
----------
28+

‎doc/metric_learn.rca.rst

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Relative Components Analysis (RCA)
2+
==================================
3+
4+
.. automodule:: metric_learn.rca
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import RCA
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
rca = RCA()
24+
C = RCA.prepare_constraints(Y, num_chunks=30, chunk_size=2)
25+
rca.fit(X, C)
26+
27+
References
28+
------------------
29+
`Adjustment learning and relevant component analysis <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.19.2871&rep=rep1&type=pdf>`_ Noam Shental, et al.

‎doc/metric_learn.rst

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
metric_learn package
2+
====================
3+
4+
Submodules
5+
----------
6+
7+
.. toctree::
8+
9+
metric_learn.base_metric
10+
metric_learn.itml
11+
metric_learn.lfda
12+
metric_learn.lmnn
13+
metric_learn.lsml
14+
metric_learn.nca
15+
metric_learn.rca
16+
metric_learn.sdml
17+
18+
Module contents
19+
---------------
20+
21+
.. automodule:: metric_learn
22+
:members:
23+
:undoc-members:
24+
:show-inheritance:

‎doc/metric_learn.sdml.rst

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Sparse Determinant Metric Learning (SDML)
2+
=========================================
3+
4+
.. automodule:: metric_learn.sdml
5+
:members:
6+
:undoc-members:
7+
:inherited-members:
8+
:show-inheritance:
9+
10+
Example Code
11+
------------
12+
13+
::
14+
15+
import numpy as np
16+
from metric_learn import SDML
17+
from sklearn.datasets import load_iris
18+
19+
iris_data = load_iris()
20+
X = iris_data['data']
21+
Y = iris_data['target']
22+
23+
sdml = SDML()
24+
W = SDML.prepare_constraints(Y, X.shape[0], 1500)
25+
sdml.fit(X, W)
26+
27+
References
28+
------------------

0 commit comments

Comments
 (0)