Improve backend docstrings (#482)

* Empty commit

* Add section about backends in docs/quickstart.rst

* Add docs/backend.rst

* Add examples using the PyTorch backend in dtw, soft_dtw, soft_dtw_alignment, cdist_soft_dtw, cdist_soft_dtw_normalized

* Add import torch in examples using PyTorch backend

* Improve backend.rst

* Skip doctest if Torch is not installed

* Remove print in docstrings

* Add import pytest in docstrings when Torch is not installed

* Improve backend.rst

* Complete backend.rst

* Remove useless # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS

* Remove try import torch from docstrings and skip doctests when torch is not installed.

* Skip doctests for linux_without_torch when torch is not installed in azure-pipelines.yml

* Improve backend.rst

* Add  # noqa: E501 after docstrings with lines too long

* Add blank line to fix a display error of the docstrings

* Empty commit

Author: YannCabanes

azure-pipelines.yml

@@ -82,7 +82,7 @@ jobs:
       python -m pip install pytest pytest-azurepipelines
       python -m pip install scikit-learn==1.2
       python -m pip install tensorflow==2.9.0
-      python -m pytest -v tslearn/ --doctest-modules
+      python -m pytest -v tslearn/ --doctest-modules -k 'not tslearn.metrics.softdtw_variants.soft_dtw and not tslearn.metrics.softdtw_variants.cdist_soft_dtw and not tslearn.metrics.dtw_variants.dtw or tslearn.metrics.dtw_variants.dtw_'
     displayName: 'Test'
 
 

docs/backend.rst

@@ -0,0 +1,202 @@
+Backend selection and use
+=========================
+
+`tslearn` proposes different backends (`NumPy` and `PyTorch`)
+to compute time series metrics such as `DTW` and `Soft-DTW`.
+The `PyTorch` backend can be used to compute gradients of
+metric functions thanks to automatic differentiation.
+
+Backend selection
+-----------------
+
+A backend can be instantiated using the function ``instantiate_backend``.
+To specify which backend should be instantiated (`NumPy` or `PyTorch`),
+this function accepts four different kind of input parameters:
+
+* a string equal to ``"numpy"`` or ``"pytorch"``.
+* a `NumPy` array or a `Torch` tensor.
+* a Backend instance. The input backend is then returned.
+* ``None`` or anything else than mentioned previously. The backend `NumPy` is then instantiated.
+
+Examples
+~~~~~~~~
+
+If the input is the string ``"numpy"``, the ``NumPyBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> from tslearn.backend import instantiate_backend
+    >>> be = instantiate_backend("numpy")
+    >>> print(be.backend_string)
+    "numpy"
+
+If the input is the string ``"pytorch"``, the ``PyTorchBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend("pytorch")
+    >>> print(be.backend_string)
+    "pytorch"
+
+If the input is a `NumPy` array, the ``NumPyBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> import numpy as np
+    >>> be = instantiate_backend(np.array([0]))
+    >>> print(be.backend_string)
+    "numpy"
+
+If the input is a `Torch` tensor, the ``PyTorchBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> import torch
+    >>> be = instantiate_backend(torch.tensor([0]))
+    >>> print(be.backend_string)
+    "pytorch"
+
+If the input is a Backend instance, the input backend is returned.
+
+.. code-block:: python
+
+    >>> print(be.backend_string)
+    "pytorch"
+    >>> be = instantiate_backend(be)
+    >>> print(be.backend_string)
+    "pytorch"
+
+If the input is ``None``, the ``NumPyBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend(None)
+    >>> print(be.backend_string)
+    "numpy"
+
+If the input is anything else, the ``NumPyBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend("Hello, World!")
+    >>> print(be.backend_string)
+    "numpy"
+
+The function ``instantiate_backend`` accepts any number of input parameters, including zero.
+To select which backend should be instantiated (`NumPy` or `PyTorch`),
+a for loop is performed on the inputs until a backend is selected.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend(1, None, "Hello, World!", torch.tensor([0]), "numpy")
+    >>> print(be.backend_string)
+    "pytorch"
+
+If none of the inputs are related to `NumPy` or `PyTorch`, the ``NumPyBackend`` is instantiated.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend(1, None, "Hello, World!")
+    >>> print(be.backend_string)
+    "numpy"
+
+Use the backends
+----------------
+
+The names of the attributes and methods of the backends
+are inspired by the `NumPy` backend.
+
+Examples
+~~~~~~~~
+
+Create backend objects.
+
+.. code-block:: python
+
+    >>> be = instantiate_backend("pytorch")
+    >>> mat = be.array([[0 , 1], [2, 3]], dtype=float)
+    >>> print(mat)
+    tensor([[0., 1.],
+            [2., 3.]], dtype=torch.float64)
+
+Use backend functions.
+
+.. code-block:: python
+
+    >>> norm = be.linalg.norm(mat)
+    >>> print(norm)
+    tensor(3.7417, dtype=torch.float64)
+
+Choose the backend used by metric functions
+-------------------------------------------
+
+`tslearn`'s metric functions have an optional input parameter "``be``" to specify the
+backend to use to compute the metric.
+
+Examples
+~~~~~~~~
+
+.. code-block:: python
+
+    >>> import torch
+    >>> from tslearn.metrics import dtw
+    >>> s1 = torch.tensor([[1.0], [2.0], [3.0]], requires_grad=True)
+    >>> s2 = torch.tensor([[3.0], [4.0], [-3.0]])
+    >>> sim = dtw(s1, s2, be="pytorch")
+    >>> print(sim)
+    sim tensor(6.4807, grad_fn=<SqrtBackward0>)
+
+By default, the optional input parameter ``be`` is equal to ``None``.
+Note that the first line of the function ``dtw`` is:
+
+.. code-block:: python
+
+    be = instantiate_backend(be, s1, s2)
+
+Therefore, even if ``be=None``, the ``PyTorchBackend`` is instantiated and used to compute the
+DTW metric since ``s1`` and ``s2`` are `Torch` tensors.
+
+.. code-block:: python
+
+    >>> sim = dtw(s1, s2)
+    >>> print(sim)
+    sim tensor(6.4807, grad_fn=<SqrtBackward0>)
+
+Automatic differentiation
+-------------------------
+
+The `PyTorch` backend can be used to compute the gradients of the metric functions thanks to automatic differentiation.
+
+Examples
+~~~~~~~~
+
+Compute the gradient of the Dynamic Time Warping similarity measure.
+
+.. code-block:: python
+
+    >>> s1 = torch.tensor([[1.0], [2.0], [3.0]], requires_grad=True)
+    >>> s2 = torch.tensor([[3.0], [4.0], [-3.0]])
+    >>> sim = dtw(s1, s2, be="pytorch")
+    >>> sim.backward()
+    >>> d_s1 = s1.grad
+    >>> print(d_s1)
+    tensor([[-0.3086],
+            [-0.1543],
+            [ 0.7715]])
+
+Compute the gradient of the Soft-DTW similarity measure.
+
+.. code-block:: python
+
+    >>> from tslearn.metrics import soft_dtw
+    >>> ts1 = torch.tensor([[1.0], [2.0], [3.0]], requires_grad=True)
+    >>> ts2 = torch.tensor([[3.0], [4.0], [-3.0]])
+    >>> sim = soft_dtw(ts1, ts2, gamma=1.0, be="pytorch", compute_with_backend=True)
+    >>> print(sim)
+    tensor(41.1876, dtype=torch.float64, grad_fn=<SelectBackward0>)
+    >>> sim.backward()
+    >>> d_ts1 = ts1.grad
+    >>> print(d_ts1)
+    tensor([[-4.0001],
+            [-2.2852],
+            [10.1643]])

docs/quickstart.rst

@@ -10,5 +10,6 @@ look at our :doc:`API Reference <reference>`.
     installation
     gettingstarted
     variablelength
+    backend
     integration_other_software
     contributing

tslearn/metrics/dtw_variants.py

@@ -694,6 +694,31 @@ def dtw(
     >>> dtw([1, 2, 3], [1., 2., 2., 3., 4.])
     1.0
 
+    The PyTorch backend can be used to compute gradients:
+    
+    >>> import torch
+    >>> s1 = torch.tensor([[1.0], [2.0], [3.0]], requires_grad=True)
+    >>> s2 = torch.tensor([[3.0], [4.0], [-3.0]])
+    >>> sim = dtw(s1, s2, be="pytorch")
+    >>> print(sim)
+    tensor(6.4807, grad_fn=<SqrtBackward0>)
+    >>> sim.backward()
+    >>> print(s1.grad)
+    tensor([[-0.3086],
+            [-0.1543],
+            [ 0.7715]])
+
+    >>> s1_2d = torch.tensor([[1.0, 1.0], [2.0, 2.0], [3.0, 3.0]], requires_grad=True)
+    >>> s2_2d = torch.tensor([[3.0, 3.0], [4.0, 4.0], [-3.0, -3.0]])
+    >>> sim = dtw(s1_2d, s2_2d, be="pytorch")
+    >>> print(sim)
+    tensor(9.1652, grad_fn=<SqrtBackward0>)
+    >>> sim.backward()
+    >>> print(s1_2d.grad)
+    tensor([[-0.2182, -0.2182],
+            [-0.1091, -0.1091],
+            [ 0.5455,  0.5455]])
+
     See Also
     --------
     dtw_path : Get both the matching path and the similarity score for DTW
@@ -705,7 +730,7 @@ def dtw(
            spoken word recognition," IEEE Transactions on Acoustics, Speech and
            Signal Processing, vol. 26(1), pp. 43--49, 1978.
 
-    """
+    """  # noqa: E501
     be = instantiate_backend(be, s1, s2)
     s1 = to_time_series(s1, remove_nans=True, be=be)
     s2 = to_time_series(s2, remove_nans=True, be=be)