tslearn 0.6.2__tar.gz → 0.6.3__tar.gz

{tslearn-0.6.2 → tslearn-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tslearn
-Version: 0.6.2
+Version: 0.6.3
 Summary: A machine learning toolkit dedicated to time-series data
 Home-page: http://tslearn.readthedocs.io/
 Author: Romain Tavenard

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/__init__.py

@@ -1,7 +1,7 @@
 import os
 
 __author__ = 'Romain Tavenard romain.tavenard[at]univ-rennes2.fr'
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 __bibtex__ = r"""@article{JMLR:v21:20-091,
   author  = {Romain Tavenard and Johann Faouzi and Gilles Vandewiele and
              Felix Divo and Guillaume Androz and Chester Holtz and

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/backend/__init__.py

@@ -3,10 +3,11 @@ The :mod:`tslearn.backend` module provides multiple backends.
 The backends provided are NumPy and PyTorch.
 """
 
-from .backend import Backend, instantiate_backend, select_backend
+from .backend import Backend, cast, instantiate_backend, select_backend
 
 __all__ = [
     "Backend",
+    "cast",
     "instantiate_backend",
     "select_backend",
 ]

tslearn-0.6.3/tslearn/backend/backend.py

@@ -0,0 +1,120 @@
+"""The generic backend."""
+
+from tslearn.backend.numpy_backend import NumPyBackend
+
+try:
+    import torch
+
+    from tslearn.backend.pytorch_backend import PyTorchBackend
+except ImportError:
+
+    class PyTorchBackend:
+        def __init__(self):
+            raise ValueError(
+                "Could not use pytorch backend since torch is not installed"
+            )
+
+
+def instantiate_backend(*args):
+    """Select backend.
+
+    Parameter
+    ---------
+    *args : Input arguments can be Backend instance or string or array or None
+        Arguments used to define the backend instance.
+
+    Returns
+    -------
+    backend : Backend instance
+        The backend instance.
+    """
+    for arg in args:
+        if isinstance(arg, Backend):
+            return arg
+        if "numpy" in f"{type(arg)}" or "numpy" in f"{arg}".lower():
+            return Backend("numpy")
+        if "torch" in f"{type(arg)}" or "torch" in f"{arg}".lower():
+            return Backend("pytorch")
+    return Backend("numpy")
+
+
+def select_backend(data):
+    """Select backend.
+
+    Parameter
+    ---------
+    data : array-like or string or None
+        Indicates the backend to choose.
+        Optional, default equals None.
+
+    Returns
+    -------
+    backend : class
+        The backend class.
+        If data is a Numpy array or data equals 'numpy' or data is None,
+        backend equals NumpyBackend().
+        If data is a PyTorch array or data equals 'pytorch',
+        backend equals PytorchBackend().
+    """
+    if "torch" in f"{type(data)}" or "torch" in f"{data}".lower():
+        return PyTorchBackend()
+    return NumPyBackend()
+
+
+class Backend(object):
+    """Class for the  backend.
+
+    Parameter
+    ---------
+    data : array-like or string or None
+        Indicates the backend to choose.
+        If data is a Numpy array or data equals 'numpy' or data is None,
+        self.backend is set to NumpyBackend().
+        If data is a PyTorch array or data equals 'pytorch',
+        self.backend is set to PytorchBackend().
+        Optional, default equals None.
+    """
+
+    def __init__(self, data=None):
+        self.backend = select_backend(data)
+
+        for element in dir(self.backend):
+            if "__" not in element:
+                setattr(self, element, getattr(self.backend, element))
+
+        self.is_numpy = self.backend_string == "numpy"
+        self.is_pytorch = self.backend_string == "pytorch"
+
+    def get_backend(self):
+        return self.backend
+
+    def set_backend(self, data=None):
+        self.backend = select_backend(data)
+
+
+def cast(data, array_type="numpy"):
+    """Cast data to list or specific backend.
+
+    Parameters
+    ----------
+    data: array-like,
+        The input data should be a list or numpy array or torch array.
+        The data to cast.
+    array_type: string
+        The type to cast the data. It can be "numpy", "pytorch" or "list".
+
+    Returns
+    --------
+    data_cast: array-like
+        Data cast to array_type.
+    """
+    data_type_string = f"{type(data)}".lower()
+    array_type = array_type.lower()
+    if array_type == "pytorch":
+        array_type = "torch"
+    if array_type in data_type_string:
+        return data
+    if array_type == "list":
+        return data.tolist()
+    be = Backend(array_type)
+    return be.array(data)

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/backend/numpy_backend.py

@@ -81,6 +81,10 @@ class NumPyBackend(object):
         self.zeros = _np.zeros
         self.zeros_like = _np.zeros_like
 
+    @staticmethod
+    def belongs_to_backend(x):
+        return "numpy" in f"{type(x)}".lower()
+
     @staticmethod
     def cast(x, dtype):
         return x.astype(dtype)

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/backend/pytorch_backend.py

@@ -121,6 +121,10 @@ else:
 
             return _torch.tensor(val, dtype=dtype)
 
+        @staticmethod
+        def belongs_to_backend(x):
+            return "torch" in f"{type(x)}".lower()
+
         def cast(self, x, dtype):
             if _torch.is_tensor(x):
                 return x.to(dtype=dtype)

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/bases/bases.py

@@ -204,8 +204,9 @@ class BaseModelPackage:
         model = cls._byte2string(model)
 
         for k in model['hyper_params'].keys():
-            if model['hyper_params'][k] == 'None':
-                model['hyper_params'][k] = None
+            if isinstance(model['hyper_params'][k], str):
+                if model['hyper_params'][k] == 'None':
+                    model['hyper_params'][k] = None
 
         return cls._organize_model(cls, model)
 

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/metrics/ctw.py

@@ -9,20 +9,21 @@ from .utils import _cdist_generic
 
 
 def _get_warp_matrices(warp_path, be):
-    """
-    Convert warping path sequence to matrices.
+    """Convert warping path sequence to matrices.
 
     Parameters
     ----------
-    warp_path : list of tuple of two indices that are matched together
+    warp_path : list of tuple of two indices that are matched together, length = m
         First output of the dtw_path function.
     be : Backend object or string
         Backend.
 
     Returns
     -------
-    two 2D matrices of size m x T (m = number of step to match the two
-        sequences
+    Wx : array-like, shape=(m, nx)
+        Matrix. The number of steps to match the two sequences is equal to m.
+    Wy : array-like, shape=(m, ny)
+        Matrix.
     """
     be = instantiate_backend(be, warp_path[0][0])
     # number of indices for the alignment
@@ -67,10 +68,10 @@ def ctw_path(
 
     Parameters
     ----------
-    s1
-        A time series.
-    s2
-        Another time series.
+    s1 : array-like, shape=(sz1, d) or (sz1,)
+        A time series. If shape is (sz1,), the time series is assumed to be univariate.
+    s2 : array-like, shape=(sz2, d) or (sz2,)
+        Another time series. If shape is (sz2,), the time series is assumed to be univariate.
     max_iter : int (default: 100)
         Number of iterations for the CTW algorithm. Each iteration
     n_components : int (default: None)
@@ -100,7 +101,12 @@ def ctw_path(
     verbose : bool (default: True)
         If True, scores are printed at each iteration of the algorithm.
     be : Backend object or string or None
-        Backend.
+        Backend. If `be` is an instance of the class `NumPyBackend` or the string `"numpy"`,
+        the NumPy backend is used.
+        If `be` is an instance of the class `PyTorchBackend` or the string `"pytorch"`,
+        the PyTorch backend is used.
+        If `be` is `None`, the backend is determined by the input arrays.
+        See our :ref:`dedicated user-guide page <backend>` for more information.
 
     Returns
     -------
@@ -136,7 +142,7 @@ def ctw_path(
     .. [1] F. Zhou and F. Torre, "Canonical time warping for alignment of
        human behavior". NIPS 2009.
     """
-    be = instantiate_backend(be, s1)
+    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)
     s1, s2 = be.array(s1, dtype=be.float64), be.array(s2, dtype=be.float64)
@@ -215,10 +221,10 @@ def ctw(
 
     Parameters
     ----------
-    s1
-        A time series.
-    s2
-        Another time series.
+    s1 : array-like, shape=(sz1, d) or (sz1,)
+        A time series. If shape is (sz1,), the time series is assumed to be univariate.
+    s2 : array-like, shape=(sz2, d) or (sz2,)
+        Another time series. If shape is (sz2,), the time series is assumed to be univariate.
     max_iter : int (default: 100)
         Number of iterations for the CTW algorithm. Each iteration
     n_components : int (default: None)
@@ -248,7 +254,12 @@ def ctw(
     verbose : bool (default: True)
         If True, scores are printed at each iteration of the algorithm.
     be : Backend object or string or None
-        Backend.
+        Backend. If `be` is an instance of the class `NumPyBackend` or the string `"numpy"`,
+        the NumPy backend is used.
+        If `be` is an instance of the class `PyTorchBackend` or the string `"pytorch"`,
+        the PyTorch backend is used.
+        If `be` is `None`, the backend is determined by the input arrays.
+        See our :ref:`dedicated user-guide page <backend>` for more information.
 
     Returns
     -------
@@ -271,7 +282,9 @@ def ctw(
     .. [1] F. Zhou and F. Torre, "Canonical time warping for alignment of
        human behavior". NIPS 2009.
     """
-    be = instantiate_backend(be, s1)
+    be = instantiate_backend(be, s1, s2)
+    s1 = be.array(s1)
+    s2 = be.array(s2)
     return ctw_path(
         s1=s1,
         s2=s2,
@@ -311,11 +324,15 @@ def cdist_ctw(
 
     Parameters
     ----------
-    dataset1 : array-like
-        A dataset of time series
-    dataset2 : array-like (default: None)
-        Another dataset of time series. If `None`, self-similarity of
-        `dataset1` is returned.
+    dataset1 : array-like, shape=(n_ts1, sz1, d) or (n_ts1, sz1) or (sz1,)
+        A dataset of time series.
+        If shape is (n_ts1, sz1), the dataset is composed of univariate time series.
+        If shape is (sz1,), the dataset is composed of a unique univariate time series.
+    dataset2 : None or array-like, shape=(n_ts2, sz2, d) or (n_ts2, sz2) or (sz2,) (default: None)
+        Another dataset of time series. 
+        If `None`, self-similarity of `dataset1` is returned.
+        If shape is (n_ts2, sz2), the dataset is composed of univariate time series.
+        If shape is (sz2,), the dataset is composed of a unique univariate time series.
     max_iter : int (default: 100)
         Number of iterations for the CTW algorithm. Each iteration
     n_components : int (default: None)
@@ -356,12 +373,17 @@ def cdist_ctw(
         `Glossary <https://joblib.readthedocs.io/en/latest/parallel.html#parallel-reference-documentation>`__
         for more details.
     be : Backend object or string or None
-        Backend.
+        Backend. If `be` is an instance of the class `NumPyBackend` or the string `"numpy"`,
+        the NumPy backend is used.
+        If `be` is an instance of the class `PyTorchBackend` or the string `"pytorch"`,
+        the PyTorch backend is used.
+        If `be` is `None`, the backend is determined by the input arrays.
+        See our :ref:`dedicated user-guide page <backend>` for more information.
 
     Returns
     -------
-    cdist : numpy.ndarray
-        Cross-similarity matrix
+    cdist : array-like, shape=(n_ts1, n_ts2)
+        Cross-similarity matrix.
 
     Examples
     --------
@@ -382,7 +404,7 @@ def cdist_ctw(
     .. [1] F. Zhou and F. Torre, "Canonical time warping for alignment of
        human behavior". NIPS 2009.
     """  # noqa: E501
-    be = instantiate_backend(be, dataset1)
+    be = instantiate_backend(be, dataset1, dataset2)
     return _cdist_generic(
         dist_fun=ctw,
         dataset1=dataset1,

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/metrics/cycc.py

@@ -12,14 +12,16 @@ def normalized_cc(s1, s2, norm1=-1.0, norm2=-1.0):
 
     Parameters
     ----------
-    s1 : array-like, shape=[sz, d], dtype=float64
-    s2 : array-like, shape=[sz, d], dtype=float64
+    s1 : array-like, shape=(sz, d), dtype=float64
+        A time series.
+    s2 : array-like, shape=(sz, d), dtype=float64
+        Another time series.
     norm1 : float64, default=-1.0
     norm2 : float64, default=-1.0
 
     Returns
     -------
-    norm_cc : array-like, shape=[2 * sz - 1], dtype=float64
+    norm_cc : array-like, shape=(2 * sz - 1), dtype=float64
     """
     assert s1.shape[1] == s2.shape[1]
     sz = s1.shape[0]
@@ -54,15 +56,17 @@ def cdist_normalized_cc(dataset1, dataset2, norms1, norms2, self_similarity):
 
     Parameters
     ----------
-    dataset1 : array-like, shape=[n_ts1, sz, d], dtype=float64
-    dataset2 : array-like, shape=[n_ts2, sz, d], dtype=float64
-    norms1 : array-like, shape=[n_ts1], dtype=float64
-    norms2 : array-like, shape=[n_ts2], dtype=float64
+    dataset1 : array-like, shape=(n_ts1, sz, d), dtype=float64
+        A dataset of time series.
+    dataset2 : array-like, shape=(n_ts2, sz, d), dtype=float64
+        Another dataset of time series.
+    norms1 : array-like, shape=(n_ts1,), dtype=float64
+    norms2 : array-like, shape=(n_ts2,), dtype=float64
     self_similarity : bool
 
     Returns
     -------
-    dists : array-like, shape=[n_ts1, n_ts2], dtype=float64
+    dists : array-like, shape=(n_ts1, n_ts2), dtype=float64
     """
     n_ts1, sz, d = dataset1.shape
     n_ts2 = dataset2.shape[0]
@@ -97,17 +101,18 @@ def y_shifted_sbd_vec(ref_ts, dataset, norm_ref, norms_dataset):
 
     Parameters
     ----------
-    ref_ts : array-like, shape=[sz, d], dtype=float64
+    ref_ts : array-like, shape=(sz, d), dtype=float64
         Time series of reference.
-    dataset : array-like, shape=[n_ts, sz, d], dtype=float64
+    dataset : array-like, shape=(n_ts, sz, d), dtype=float64
         Time series dataset.
     norm_ref : float64
-    norms_dataset : array-like, shape=[n_ts], dtype=float64
+    norms_dataset : array-like, shape=(n_ts,), dtype=float64
         Norms of the time series dataset.
 
     Returns
     -------
-    dataset_shifted : array-like, shape=[n_ts, sz, d], dtype=float64
+    dataset_shifted : array-like, shape=(n_ts, sz, d), dtype=float64
+        Shifted dataset.
     """
     n_ts = dataset.shape[0]
     sz = dataset.shape[1]

{tslearn-0.6.2 → tslearn-0.6.3}/tslearn/metrics/cysax.py

@@ -13,13 +13,14 @@ def inv_transform_paa(dataset_paa, original_size):
 
     Parameters
     ----------
-    dataset_paa : array-like, shape=[n_ts, sz, d], dtype=float64
+    dataset_paa : array-like, shape=(n_ts, sz, d), dtype=float64
         A dataset of PAA series.
     original_size : int32
+        Length of the original time series.
 
     Returns
     -------
-    dataset_out : array-like, shape=[n_ts, original_size, d], dtype=float64
+    dataset_out : array-like, shape=(n_ts, original_size, d), dtype=float64
         A dataset of time series corresponding to the provided
         representation.
     """
@@ -39,12 +40,14 @@ def cydist_sax(sax1, sax2, breakpoints, original_size):
 
     Parameters
     ----------
-    sax1 : array-like, shape=[sz, d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    sax1 : array-like, shape=(sz, d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         SAX representation of a time series.
-    sax2 : array-like, shape=[sz, d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    sax2 : array-like, shape=(sz, d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         SAX representation of another time series.
     breakpoints : array-like, ndim=1, dtype=float64
+        The breakpoints used to assign the alphabet symbols.
     original_size : int64 (Linux and MacOS) or int32 (Windows)
+        Length of the original time series.
 
     Returns
     -------
@@ -77,14 +80,15 @@ def inv_transform_sax(dataset_sax, breakpoints_middle_, original_size):
 
     Parameters
     ----------
-    dataset_sax : array-like, shape=[n_ts, sz, d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    dataset_sax : array-like, shape=(n_ts, sz, d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         A dataset of SAX series.
     breakpoints_middle_ : array-like, ndim=1, dtype=float64
     original_size : int64 (Linux and MacOS) or int32 (Windows)
+        Length of the original time series.
 
     Returns
     -------
-    dataset_out : array-like, shape=[n_ts, original_size, d], dtype=float64
+    dataset_out : array-like, shape=(n_ts, original_size, d), dtype=float64
     """
     n_ts, sz, d = dataset_sax.shape
     seg_sz = original_size // sz
@@ -105,12 +109,12 @@ def cyslopes(dataset, t0):
 
     Parameters
     ----------
-    dataset : array-like, shape=[n_ts, sz, d], dtype=float64
+    dataset : array-like, shape=(n_ts, sz, d), dtype=float64
     t0 : int32
 
     Returns
     -------
-    dataset_out : array-like, shape=[n_ts, d], dtype=float64
+    dataset_out : array-like, shape=(n_ts, d), dtype=float64
     """
     n_ts, sz, d = dataset.shape
     dataset_out = np.empty((n_ts, d))
@@ -135,17 +139,19 @@ def cydist_1d_sax(
 
     Parameters
     ----------
-    sax1 : array-like, shape=[sz, 2 * d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    sax1 : array-like, shape=(sz, 2 * d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         1d-SAX representation of a time series.
-    sax2 : array-like, shape=[sz, 2 * d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    sax2 : array-like, shape=(sz, 2 * d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         1d-SAX representation of another time series.
     breakpoints_avg_middle_ : array-like, ndim=1, dtype=float64
     breakpoints_slope_middle_ : array-like, ndim=1, dtype=float64
     original_size : int64 (Linux and MacOS) or int32 (Windows)
+        Length of the original time series.
 
     Returns
     -------
     dist_1d_sax : float64
+        1d-SAX distance.
 
     Notes
     -----
@@ -187,15 +193,16 @@ def inv_transform_1d_sax(
 
     Parameters
     ----------
-    dataset_sax : array-like, shape=[n_ts, sz, 2 * d], dtype=float64 (Linux and MacOS) or float32 (Windows)
+    dataset_sax : array-like, shape=(n_ts, sz, 2 * d), dtype=float64 (Linux and MacOS) or float32 (Windows)
         A dataset of SAX series.
     breakpoints_avg_middle_ : array-like, ndim=1, dtype=float64
     breakpoints_slope_middle_ : array-like, ndim=1, dtype=float64
     original_size : int64 (Linux and MacOS) or int32 (Windows)
+        Length of the original time series.
 
     Returns
     -------
-    dataset_out : array-like, shape=[n_ts, original_size, d], dtype=float64
+    dataset_out : array-like, shape=(n_ts, original_size, d), dtype=float64
         A dataset of time series corresponding to the provided
             representation.
     """