Add frechet metric

CHANGELOG.md

@@ -23,6 +23,7 @@ Changelogs for this project are recorded in this file since v0.2.0.
 
 * `per_timeseries` and `per_feature` options for min-max and mean-variance scalers ([#536](https://github.com/tslearn-team/tslearn/issues/536))
 * `TimeSeriesImputer`class: missing value imputer for time series ([#564](https://github.com/tslearn-team/tslearn/issues/564))
+* Frechet metrics and KNeighbors integration ([#402](https://github.com/tslearn-team/tslearn/issues/402)
 
 ## [v0.6.4]
 

azure-pipelines.yml

@@ -299,7 +299,7 @@ jobs:
       set -xe
       python -m pip install pytest-azurepipelines
       pip list
-      python -m pytest -v tslearn/ --doctest-modules -k 'not test_ and 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_ or test_all_estimators'
+      python -m pytest -v tslearn/ --doctest-modules -k 'not test_ and not tslearn.metrics.softdtw_variants.soft_dtw and not tslearn.metrics.frechet.frechet and not tslearn.metrics.softdtw_variants.cdist_soft_dtw and not tslearn.metrics.dtw_variants.dtw or tslearn.metrics.dtw_variants.dtw_ or test_all_estimators'
     displayName: 'Doctest'
 
 - job: 'codecov'  # must be a separate job to only disable Numbas's JIT here

docs/_static/custom.css

@@ -1,33 +1,4 @@
-code {
-    color: #055781;
-}
-
-table.longtable tbody tr:nth-child(even) {
-    background-color: #FDFDFD;
-
-}
-table.longtable tbody tr:nth-child(odd) {
-    background-color: #F0F7FA;
-}
-
-table.longtable tbody tr {
-    border-style: solid none solid none;
-    border-width: 1px 0 1px 0;
-    border-color: #ddd;
-}
-
-table.longtable tbody td {
-    border-color: #ddd;
-}
-
-.alert-info {
-    background-color: #d2edf6;
-    border-color: #d2edf6;
-    color: #555555;
-}
-
-@media screen and (min-width: 768px) and (max-width: 992px) {
-    .navbar-form .form-control {
-        display: none;
-    }
+.sphx-glr-thumbcontainer{
+  text-align: center;
+  justify-content: center;
 }

docs/conf.py

@@ -83,6 +83,7 @@ def matplotlib_svg_scraper(*args, **kwargs):
     'subsection_order': ["examples/metrics", "examples/neighbors",
                          "examples/clustering", "examples/classification",
                          "examples/autodiff", "examples/misc"].index,
+    'within_subsection_order': "FileNameSortKey",
     'image_scrapers': (matplotlib_svg_scraper,),
 }
 
@@ -237,6 +238,7 @@ def matplotlib_svg_scraper(*args, **kwargs):
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/examples/metrics/plot_frechet.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+"""
+Frechet
+======================
+
+This example illustrates the use of Frechet distance between time
+series and plots the matches obtained by the method [1]_ compared to DTW.
+
+The Frechet distance is plotted in red:
+
+.. math::
+
+   Frechet(X, Y) = \max_{(i, j) \in \pi} \|X_{i} - Y_{j}\|
+
+.. [1] FRÉCHET, M. "Sur quelques points du calcul fonctionnel.
+   Rendiconti del Circolo Mathematico di Palermo", 22, 1–74, 1906.
+"""
+
+# License: BSD 3 clause
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from tslearn.metrics import frechet_path, dtw_path
+
+np.random.seed(42)
+
+nb_points = 100
+angle1 = 0.25*np.linspace(0, 4*np.pi, nb_points)
+s1 = np.sin(angle1) + 0.1 * np.random.rand(nb_points) + 1
+angle2 = np.linspace(0, 2 * np.pi, nb_points)
+s2 = 0.5 * np.sin(angle2) + 0.1 * np.random.rand(nb_points)
+
+path_dtw, _ = dtw_path(s1, s2)
+path_frechet, distance_frechet = frechet_path(s1, s2)
+
+plt.figure(figsize=(8, 4))
+ax = plt.subplot(1, 2, 1)
+ax.plot(s1)
+ax.plot(s2)
+for (i, j) in path_frechet:
+    is_max = np.linalg.norm(s1[i] - s2[j]) == distance_frechet
+    ax.plot(
+        [i, j],
+        [s1[i], s2[j]],
+        'rd:' if is_max else 'k--',
+        alpha=1 if is_max else 0.1
+    )
+ax.set_title("Frechet")
+
+ax = plt.subplot(1, 2, 2)
+ax.plot(s1)
+ax.plot(s2)
+for (i, j) in path_dtw:
+    ax.plot([i, j],[s1[i], s2[j]], 'k--', alpha=0.1)
+ax.set_title("DTW")
+
+plt.tight_layout()
+plt.show()

docs/gen_modules/tslearn.metrics.rst

@@ -36,3 +36,7 @@ tslearn.metrics
       sigma_gak
       gamma_soft_dtw
       SoftDTWLossPyTorch
+      frechet
+      frechet_path
+      frechet_path_from_metric
+      cdist_frechet

tslearn/metrics/__init__.py

@@ -23,34 +23,52 @@
                                SoftDTW)
 from .soft_dtw_loss_pytorch import SoftDTWLossPyTorch
 from .cycc import cdist_normalized_cc, y_shifted_sbd_vec
+from .frechet import frechet, frechet_path, frechet_path_from_metric, cdist_frechet
 
 __author__ = 'Romain Tavenard romain.tavenard[at]univ-rennes2.fr'
 
-TSLEARN_VALID_METRICS = ["ctw", "dtw", "gak", "sax", "softdtw", "lcss"]
-VARIABLE_LENGTH_METRICS = ["ctw", "dtw", "gak", "sax", "softdtw", "lcss"]
+TSLEARN_VALID_METRICS = ["ctw", "dtw", "gak", "sax", "softdtw", "lcss", "frechet"]
+VARIABLE_LENGTH_METRICS = ["ctw", "dtw", "gak", "sax", "softdtw", "lcss", "frechet"]
 
 __all__ = [
-    "TSLEARN_VALID_METRICS", "VARIABLE_LENGTH_METRICS",
-
-    "dtw", "dtw_limited_warping_length",
-    "dtw_path_limited_warping_length", "subsequence_path",
-    "subsequence_cost_matrix",
-    "dtw_path", "dtw_path_from_metric",
-    "dtw_subsequence_path", "cdist_dtw",
+    "TSLEARN_VALID_METRICS",
+    "VARIABLE_LENGTH_METRICS",
     "GLOBAL_CONSTRAINT_CODE",
-    "lb_envelope", "lb_keogh",
-    "sakoe_chiba_mask", "itakura_mask",
-    "lcss", "lcss_path", "lcss_path_from_metric",
-
-    "ctw_path", "ctw", "cdist_ctw",
-
+    "dtw",
+    "dtw_limited_warping_length",
+    "dtw_path_limited_warping_length",
+    "subsequence_path",
+    "subsequence_cost_matrix",
+    "dtw_path",
+    "dtw_path_from_metric",
+    "dtw_subsequence_path",
+    "cdist_dtw",
+    "lb_envelope",
+    "lb_keogh",
+    "sakoe_chiba_mask",
+    "itakura_mask",
+    "lcss",
+    "lcss_path",
+    "lcss_path_from_metric",
+    "ctw_path",
+    "ctw",
+    "cdist_ctw",
     "cdist_sax",
-
-    "cdist_soft_dtw", "cdist_gak",
-    "cdist_soft_dtw_normalized", "gak", "soft_dtw", "soft_dtw_alignment",
-    "sigma_gak", "gamma_soft_dtw", "SquaredEuclidean", "SoftDTW",
-
+    "cdist_soft_dtw",
+    "cdist_gak",
+    "cdist_soft_dtw_normalized",
+    "gak",
+    "soft_dtw",
+    "soft_dtw_alignment",
+    "sigma_gak",
+    "gamma_soft_dtw",
+    "SquaredEuclidean",
+    "SoftDTW",
     "SoftDTWLossPyTorch",
-
-    "cdist_normalized_cc", "y_shifted_sbd_vec"
+    "cdist_normalized_cc",
+    "y_shifted_sbd_vec",
+    "frechet",
+    "frechet_path",
+    "frechet_path_from_metric",
+    "cdist_frechet"
 ]