Deprecate functions for specific versions of Dynamic Time Warping

[johannfaouzi]

This PR deprecates the functions for specific versions of Dynamic Time Warping. Similarly to scipy.optimize.minimize, only the main function is in the public API, while all the functions for the specific methods are private.

Notable changes:

• All dtw_ functions are deprecated in 0.11 and will be removed in 0.12.
• The corresponding privates functions, _dtw_*, are kept and their docstrings are updated to describe only the method-specific parameters.
• Each version has its own page in the documentation, thanks to a custom Sphinx directive that is heavily inspired from the scipy-optimize custom directive.
• A new function show_options has been added to show the options for each method.

Some stuff in this PR is not related to this topic, just maintenance updates.

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@b0907bc). Click here to learn what that means.
The diff coverage is 99.83%.

@@            Coverage Diff            @@
##             master      #63   +/-   ##
=========================================
  Coverage          ?   98.36%           
=========================================
  Files             ?       91           
  Lines             ?     4826           
  Branches          ?        0           
=========================================
  Hits              ?     4747           
  Misses            ?       79           
  Partials          ?        0

Impacted Files	Coverage Δ
pyts/preprocessing/transformer.py	96.42% <ø> (ø)
pyts/multivariate/utils/utils.py	100% <ø> (ø)
pyts/approximation/sax.py	100% <ø> (ø)
pyts/metrics/__init__.py	100% <ø> (ø)
pyts/utils/utils.py	100% <ø> (ø)
pyts/decomposition/ssa.py	100% <ø> (ø)
pyts/metrics/boss.py	100% <ø> (ø)
pyts/transformation/weasel.py	99.35% <100%> (ø)
pyts/image/mtf.py	100% <100%> (ø)
pyts/bag_of_words/tests/test_bow.py	100% <100%> (ø)
... and 30 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b0907bc...e21face. Read the comment docs.

[johannfaouzi]

Deprecated functions:

• dtw_classic
• dtw_region
• dtw_sakoechiba
• dtw_itakura
• dtw_multiscale
• dtw_fast

Updated function:

• dtw

New function:

• show_options

New pages in the documentation:

• dtw(method='classic')
• dtw(method='region')
• dtw(method='sakoechiba')
• dtw(method='itakura')
• dtw(method='multiscale')
• dtw(method='fast')

[johannfaouzi]

@hichamjanati Feel free to add any comment regarding this PR (especially on the docstrings, if the descriptions are clear enough).

[hichamjanati]

So all dtw_method functions are deprecated but when a specific method arg is passed to dtw the private funcs _dtw_method are called ?

Is the plan is to remove those in the future as well and keep the minimal code:
-> compute region
-> compute accumulated cost

• eventually the fast and multi-resolution loops in private funcs ?

[johannfaouzi]

So all dtw_method functions are deprecated but when a specific method arg is passed to dtw the private funcs _dtw_method are called ?

Is the plan is to remove those in the future as well and keep the minimal code:
-> compute region
-> compute accumulated cost

• eventually the fast and multi-resolution loops in private funcs ?

For the moment the private _dtw_* functions are indeed called. I don't mind having fewer functions to make it simpler, but the code is already here and is tested, and adding new methods could easily be done by creating a new private _dtw_* function that would make use of existing functions.

We also need a function for each method, just to have the corresponding docstring for the description of the options (although we could create a function with this docstring that would do nothing).

[hichamjanati]

These descriptions are better than the ones provided in the individual docstrings. Maybe it's worth replacing them with these.

[johannfaouzi]

It's easier because we can talk about all the methods and how they relate to each other, while the individual docstrings need to be independent.

It's quite similar to scipy.optimize.minimize: the Notes section is very detailed, while the docstring for each method (e.g. minimize(method='Nelder-Mead')) is very short and does not give much information.

[hichamjanati]

Ah right, I forgot about the individual pages in the doc. Well the duplicated code is very small, I think it's not worth changing if we have to replace the func with empty ones.

[hichamjanati]

Good for me :) !