Skip to content

Add documentation for the new API #133

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 33 commits into from
Dec 20, 2018
Merged

Add documentation for the new API #133

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
61856b3
Create some text to initialize the PR
Nov 21, 2018
d5dd517
DOC: add doc outline
Dec 3, 2018
b54ee34
DOC: Add data visualisation to possible examples
Dec 3, 2018
7495b68
Update documentation outline
Dec 11, 2018
18325cd
Add doc from master
Dec 13, 2018
0ddaee3
DOC: add beginning of doc tree
Dec 17, 2018
e998652
DOC: add some beginning of example to get started with the examples s…
Dec 17, 2018
41b9182
DOC: modify gitignore to ignore auto_examples
Dec 17, 2018
0adb3c0
WIP: add preprocessor section and some section about weakly supervise…
Dec 19, 2018
26306ba
A few style improvements (text wraping to line limit, better referenc…
Dec 19, 2018
4eb8495
Address https://github.com/metric-learn/metric-learn/pull/133#pullreq…
Dec 19, 2018
3db2653
raise instead of return
Dec 20, 2018
813f658
Merge branch 'new_api_design' into doc/add_documentation
Dec 20, 2018
3891b93
Fix quickstart example
Dec 20, 2018
7dcfb54
Emphasize scikit-learn compatibility
Dec 20, 2018
1b83569
Update introduction with new methods
Dec 20, 2018
70f16a9
address https://github.com/metric-learn/metric-learn/pull/133#discuss…
Dec 20, 2018
ed0a00e
explain what happens when preprocessor=None
Dec 20, 2018
868d42b
Precisions in doc about the input accepted by the preprocessor
Dec 20, 2018
1fe3357
address https://github.com/metric-learn/metric-learn/pull/133#discuss…
Dec 20, 2018
ea487b7
Better formulation of sentences
Dec 20, 2018
16ba60a
change title formatting in index
Dec 20, 2018
95f0702
Fix references and some numering issue
Dec 20, 2018
6cb328f
Reformat link to preprocessor
Dec 20, 2018
ff4d30e
Fix automatic link to algorithms for the supervised section
Dec 20, 2018
37cd11c
Reformatting and adding examples about supervised version in the end …
Dec 20, 2018
6eee862
add precisions in the intro
Dec 20, 2018
bee4a8c
add precisions for score_pairs in the intro
Dec 20, 2018
d49ba68
Change examples for weakly supervised section
Dec 20, 2018
202e3fe
add _Supervised section in Supervised section
Dec 20, 2018
c107584
change examples in weakly supervised section
Dec 20, 2018
9de2e9c
fix empty module contents
Dec 20, 2018
1371122
rename sandwich.py into plot_sandwich.py to be found by sphinx-gallery
Dec 20, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/metric_learn.preprocessor.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Just some text to initialize the PR
36 changes: 36 additions & 0 deletions doc/outline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
documentation outline:


- Getting started/Quick Start:

- Explanation of what metric learning is, and what is the purpose of this package
- installation
- a very quick example on how to import an algo (supervised or not ?) and how to do fit (and predict ?) (and split train and test) on some custom dataset (maybe sklearn.datasets.load_lfw_pairs ?)

- User Guide/List of algorithms:

- Supervised Metric Learning: (add links to examples/images from examples at the right place in the description)
- Problem setting
- Input data (+ see Preprocessor section)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only going to be simple usage of preprocessor and then talk about more details in the preprocessor section, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, something like: input data: a 2D array-like X (or 1D array-like of indices, see preprocessor section)

- What you can do after fit (transform...)

- Weakly Supervised Metric Learning: (add links to examples/images from examples at the right place in the description)
- Problem setting
- Input data (+ See Preprocessor section)
- What you can do after fit (predict/score, tranform...)
- Scikit-learn compatibility (compatible with grid search + link to example of grid search)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might also be good to show a sklearn Pipeline

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I agree, since the pipeline (Metric Learner, KNN) for instance, represents a major use case of metric learning for classification


- Usage of the Preprocessor:
- Purpose (performance)
- Use (as an argument "preprocessor" in every metric learner)


- Examples/Tutorials:
- One example with faces (prediction if same/different person)
- One example of grid search to compare different algorithms (mmc, itml etc)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the goal is to do the following in order:

  1. grid search for each metric learning algorithm
  2. grid search for a classifier (same classification algorithm)
  3. and then compare the results using classification metrics?

Right? Or are you only comparing the visualization after metric transformation (if so, maybe this could be combined with "Data visualisation" section)?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking only grid search for Weakly Supervised Algorithms like MMC, the score being the accuracy score on predicting if a pair is positive/negative, since this case is the most unusual for users used to classic train/test sets of points and not pairs. But indeed we could also make a grid search on pipelines (SupervisedMetricLearner, KNN) for instance, like a regular classifier, with a classification accuracy score.
And I don't know if you were refering to it by 1., but maybe for Supervised Learners we could also do a GridSearch with the scoring of Weakly Supervised Algorithms (we would split the points X traditionnally, but on the test set we would sample some pairs and then evaluate the accuracy of score_pairs) I don't know if this kind of scoring could is a traditional option for Supervised Metric Learners ? @bellet any opinion on this ?

And I agree that it would be interesting to see the impact of hyperparameters tuning on data visualization: maybe this could make an example in the data visualization section indeed

- Clustering with side information
- Instance retrieval
- Data visualisation

- API:
- doc automatically generated by docstrings