Re-write the user guide

The major change here was the user guide section; it was completely rewritten. I tried to:

• Write about every algorithm that we have
• Provide some intuitions on how the stuff works
• Provide a copy and paste code snipped.

I'm working these issues #22 (closed), #21 (closed) and #20 (closed) with this PR.

Yeap, it failed. It is so annoying. I cannot see the warning even settin keep_warnings=True in conf.py.

added 1 commit

• 050ec58f - Fix sphinx warnings

Compare with previous version

added 1 commit

• 1a909059 - Fixed doc tests

Compare with previous version

Fixed the doc tests.

added 1 commit

• 2fb80fed - Fixed python 3 issues

Compare with previous version

assigned to @amohammadi

@tiago.pereira I am reviewing this and doing some changes in this branch.

Awesome, go for it.

Thanks.

Some comments:

• Why do you call mixtures, centroids in the GMM plots? I think centroids only makes sense in k-means. In GMM, maybe we can call them means, gaussians, clusters? or maybe centroids is good as is!
• The figure in MAP adaptation is confusing. What is the class of new data?
• What is T in eq 9 (GMM Statistics)?
• The i-vector training requires a lot of data. The figures from the iris dataset does not look good. Maybe we can mention the dataset is small?
• What does enroll mean in PLDA? What is PLDABase for?
• Maybe you mention that score normalization is for biometrics?
• What does Features com lista de listas mean? :D
• Can we have references for znorm, tnorm, ztnorm, please or score normalization?
• I did not read the changes in Python API!

Some changes I did:

• wrapped the text to 80 characters in a line, cleaned up Python code, improved plots
• moved "Session Variability Modeling with Gaussian Mixture Models" into its own section
• Moved the EM explanation from index to user guide.

added 1 commit

• a952f9c6 - Tidy up docs and plots

Compare with previous version

assigned to @tiago.pereira

@tiago.pereira you can look at the changes that I did using this link: https://gitlab.idiap.ch/bob/bob.learn.em/merge_requests/24/diffs?diff_id=2683&expand_all_diffs=1&start_sha=2fb80fed1b9e7437d8dcc10d34a023de669f9586

Sorry for the big diff

added 2 commits

• d05af9c5 - modified README, updated conf.py [skip ci]
• 272e5384 - Merge remote-tracking branch 'origin/python36' into 22-documentation-of-this-package-sucks

Compare with previous version

mentioned in issue bob.bio.gmm#18 (closed)

Hey @amohammadi, thanks for the review.

I will answer the issues in line

• Why do you call mixtures, centroids in the GMM plots? I think centroids only makes sense in k-means. In GMM, maybe we can call them means, gaussians, clusters? or maybe centroids is good as is!

It doesn't matter. We can call them, centroids, mixtures, gaussians....

• The figure in MAP adaptation is confusing. What is the class of new data?

Yeah, I know. I will change this example

• What is T in eq 9 (GMM Statistics)?

T is the number of samples used to generate the stats. (file:///Users/tiago.pereira/Documents/gitlab/bob.learn.em/html/py_api.html#bob.learn.em.GMMStats.t)

• The i-vector training requires a lot of data. The figures from the iris dataset does not look good. Maybe we can mention the dataset is small?

Yes, I did my best to make it nicer, but it is still crap. I tried to plot raw iVectors, then Whitening, then Whitening + WCCN, .... I will see what hack I can do to make it nicer.

• What does enroll mean in PLDA? What is PLDABase for?

Ok, I will spend some time on it.

• Maybe you mention that score normalization is for biometrics? Score normalization is for everything.

• What does Features com lista de listas mean? :D

Ops :-P

• Can we have references for znorm, tnorm, ztnorm, please or score normalization?

  Yes we can

• I did not read the changes in Python API!

Some changes I did:

• wrapped the text to 80 characters in a line, cleaned up Python code, improved plots

Awesome, thanks

• moved "Session Variability Modeling with Gaussian Mixture Models" into its own section

Fine

• Moved the EM explanation from index to user guide.

Fine

changed milestone to %Bob 2.7.x release

Thank you @tiago.pereira . I will add this to our Bob 2.7 milestone. If you think you need more time, please remove the milestone.

• The i-vector training requires a lot of data. The figures from the iris dataset does not look good. Maybe we can mention the dataset is small?

Yes, I did my best to make it nicer, but it is still crap. I tried to plot raw iVectors, then Whitening, then Whitening + WCCN, .... I will see what hack I can do to make it nicer.

You don't to make it nicer just mention that it needs more data to train and work properly.

added 3 commits

• d810b588 - Added a shallow input test. Issue #21 (closed)
• fbba17a6 - Changed the MAP example
• 9c0b3611 - Improved the documentation

Compare with previous version

added 1 commit

• 6039cd09 - Fixed bug introduced in the train

Compare with previous version