tslearn

https://tslearn.readthedocs.io/en/stable/
Admin
tslearn is a Python package providing machine learning tools for time series analysis, built on...
Tokens:260,817
Snippets:1,745
Trust Score:8.3
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install tslearn with all features

Source: https://tslearn.readthedocs.io/en/stable/installation.html

Install tslearn with the all_features extra to enable all features provided in the package.

```bash
python -m pip install tslearn[all_features]
```

--------------------------------

### Install latest tslearn from GitHub

Source: https://tslearn.readthedocs.io/en/stable/installation.html

Install the latest development version of tslearn directly from the GitHub repository.

```bash
python -m pip install https://github.com/tslearn-team/tslearn/archive/main.zip
```

--------------------------------

### Install tslearn with pip

Source: https://tslearn.readthedocs.io/en/stable/installation.html

Use pip to install tslearn from PyPI. This should work fine, preferably in a dedicated virtual environment.

```bash
python -m pip install tslearn
```

--------------------------------

### Install certifi package

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/tslearn.datasets.html

Alternatively, install the certifi package to resolve SSL certificate errors when downloading datasets.

```bash
pip install certifi
```

--------------------------------

### Install tslearn with conda

Source: https://tslearn.readthedocs.io/en/stable/installation.html

Use conda to install tslearn from the conda-forge channel. This is the easiest method, preferably in a dedicated environment.

```bash
conda install -c conda-forge tslearn
```

--------------------------------

### Install test dependencies and run pytest with coverage

Source: https://tslearn.readthedocs.io/en/stable/contributing.html

Install the package with test and all-features extras, then run pytest with coverage to run tests locally.

```bash
$ pip install -e .[tests,all_features]
$ pytest --cov

```

--------------------------------

### Install and run flake8 for PEP8/PEP257 checks

Source: https://tslearn.readthedocs.io/en/stable/contributing.html

Install flake8 and run it to check for PEP8 or PEP257 errors in one file, a folder, or only the modified code.

```bash
$ pip install flake8
$ flake8 path/to/module.py  # check for errors in one file
$ flake8 path/to/folder  # check for errors in all the files in a folder
$ git diff -u | flake8 --diff  # check for errors in the modified code only

```

--------------------------------

### PyTorch backend gradient example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.frechet.html

Demonstrates using the PyTorch backend to compute gradients. The example creates tensors with requires_grad=True, computes the Frechet similarity, and then calls backward() to obtain the gradient of s1.

```python
>>> import torch
>>> s1 = torch.tensor([[1.0], [2.0], [3.0]], requires_grad=True)
>>> s2 = torch.tensor([[3.0], [4.0], [-3.0]])
>>> sim = frechet(s1, s2, be="pytorch")
>>> print(sim)
tensor(6., dtype=torch.float64, grad_fn=<SqrtBackward0>)
>>> sim.backward()
>>> print(s1.grad)
tensor([[0.],
        [0.],
        [1.]])
```

--------------------------------

### Compute gamma_soft_dtw with example dataset

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.gamma_soft_dtw.html

Shows how to compute the gamma parameter for Soft-DTW using a small dataset. The example sets n_samples=200 and random_state=0, and the output is approximately 8.0.

```python
>>> dataset = [[1, 2, 2, 3], [1., 2., 3., 4.]]
>>> float(gamma_soft_dtw(dataset=dataset,
...                      n_samples=200,
...                      random_state=0))
8.0...
```

--------------------------------

### to_sklearn_dataset examples

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/utils/tslearn.utils.to_sklearn_dataset.html

Shows two example calls to to_sklearn_dataset. The first returns the transformed dataset and its dimensionality when return_dim=True. The second pads shorter series with NaN to produce a rectangular array.

```python
>>> to_sklearn_dataset([[1, 2]], return_dim=True)
(array([[1., 2.]]), 1)
>>> to_sklearn_dataset([[1, 2], [1, 4, 3]])
array([[ 1.,  2., nan],
       [ 1.,  4.,  3.]])
```

--------------------------------

### PyTorch backend 2D example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.frechet.html

Shows the PyTorch backend with a two-dimensional time series. The example computes the Frechet similarity and its gradient with respect to the input tensor s1_2d.

```python
>>> 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 = frechet(s1_2d, s2_2d, be="pytorch")
>>> print(sim)
tensor(8.4853, dtype=torch.float64, grad_fn=<SqrtBackward0>)
>>> sim.backward()
>>> print(s1_2d.grad)
tensor([[0.0000, 0.0000],
        [0.0000, 0.0000],
        [0.7071, 0.7071]])
```

--------------------------------

### check_equal_size examples

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/utils/tslearn.utils.check_equal_size.html

These examples show the expected return values for different datasets. The function returns True when all time series have the same size, False when they differ, and True for an empty dataset.

```python
>>> check_equal_size([[1, 2, 3], [4, 5, 6], [5, 3, 2]])
True
>>> check_equal_size([[1, 2, 3, 4], [4, 5, 6], [5, 3, 2]])
False
>>> check_equal_size([])
True
```

--------------------------------

### Convert cesium TimeSeries to tslearn array with from_cesium_dataset

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/utils_conv/tslearn.utils.from_cesium_dataset.html

Shows how to transform a cesium-formatted dataset into a tslearn array. Requires cesium to be installed. The example creates a list of cesium TimeSeries objects and passes them to from_cesium_dataset, then prints the resulting shape.

```python
>>> from cesium.time_series import TimeSeries
>>> cesium_ds = [TimeSeries(m=numpy.array([1, 2, 3, 4]))]
>>> tslearn_arr = from_cesium_dataset(cesium_ds)
>>> tslearn_arr.shape
(1, 4, 1)
>>> cesium_ds = [
...     TimeSeries(m=numpy.array([[1, 2, 3, 4],
...                               [5, 6, 7, 8]]))
... ]
>>> tslearn_arr = from_cesium_dataset(cesium_ds)
>>> tslearn_arr.shape
(1, 4, 2)
```

--------------------------------

### Build documentation locally

Source: https://tslearn.readthedocs.io/en/stable/contributing.html

Install documentation dependencies, change to the docs directory, and run make html to build the documentation.

```bash
$ pip install -e .[docs,all_features]
$ cd docs
$ make html

```

--------------------------------

### Convert between tslearn and cesium datasets

Source: https://tslearn.readthedocs.io/en/stable/integration_other_software.html

Shows how to convert between tslearn and cesium dataset formats using the to_cesium_dataset and from_cesium_dataset functions. The example creates cesium TimeSeries objects and converts them to a tslearn array, then converts a tslearn array back to cesium and checks its length. Requires the cesium package to be installed.

```python
>>> from tslearn.utils import from_cesium_dataset, to_cesium_dataset
>>> from cesium.data_management import TimeSeries
>>> from_cesium_dataset([TimeSeries(m=[1, 2]), TimeSeries(m=[1, 4, 3])])
array([[[ 1.],
        [ 2.],
        [nan]],

       [[ 1.],
        [ 4.],
        [ 3.]]])
>>> len(to_cesium_dataset([[[1], [2], [None]], [[1], [4], [3]]]))
2
```

--------------------------------

### list_datasets() example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/datasets/tslearn.datasets.UCR_UEA_datasets.html

List all datasets and verify that known datasets are present and a non-existent one is absent.

```python
>>> l = UCR_UEA_datasets().list_datasets()
>>> "PenDigits" in l
True
>>> "BeetleFly" in l
True
>>> "DatasetThatDoesNotExist" in l
False

```

--------------------------------

### Convert tsfresh DataFrame to tslearn array with from_tsfresh_dataset

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/utils_conv/tslearn.utils.from_tsfresh_dataset.html

These examples demonstrate converting a tsfresh-formatted pandas DataFrame to a tslearn array using from_tsfresh_dataset. The first two show valid conversions with different numbers of time series and dimensions, while the third shows that passing a numpy array raises a ValueError. Requires pandas to be installed.

```python
>>> import pandas as pd
>>> tsfresh_df = pd.DataFrame(columns=["id", "time", "a", "b"])
>>> tsfresh_df["id"] = [0, 0, 0]
>>> tsfresh_df["time"] = [0, 1, 2]
>>> tsfresh_df["a"] = [-1, 4, 7]
>>> tsfresh_df["b"] = [8, -3, 2]
>>> tslearn_arr = from_tsfresh_dataset(tsfresh_df)
>>> tslearn_arr.shape
(1, 3, 2)
```

```python
>>> tsfresh_df = pd.DataFrame(columns=["id", "time", "a"])
>>> tsfresh_df["id"] = [0, 0, 0, 1, 1]
>>> tsfresh_df["time"] = [0, 1, 2, 0, 1]
>>> tsfresh_df["a"] = [-1, 4, 7, 9, 1]
>>> tslearn_arr = from_tsfresh_dataset(tsfresh_df)
>>> tslearn_arr.shape
(2, 3, 1)
```

```python
>>> tsfresh_df = numpy.random.randn(10, 1, 16)
>>> from_tsfresh_dataset(
...     tsfresh_df
... )
Traceback (most recent call last):
...
ValueError: X is not a valid input tsfresh array.
```

--------------------------------

### Install Python certificates on macOS

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/tslearn.datasets.html

Run this command on macOS to install certificates for your Python installation if you encounter SSL certificate errors when downloading datasets.

```bash
/Applications/Python<VERSION>/Install\ Certificates.command
```

--------------------------------

### instantiate_backend

Source: https://tslearn.readthedocs.io/en/stable/backend.html

Documentation for the `instantiate_backend` function, which selects and returns a backend instance based on the provided inputs.

```APIDOC
## instantiate_backend

### Description
Instantiates a backend (NumPy or PyTorch) based on the provided inputs. The backend is used to compute time series metrics such as DTW and Soft-DTW, with the PyTorch backend supporting automatic differentiation.

### Method
Function call

### Endpoint
`tslearn.backend.instantiate_backend(*inputs)`

### Parameters
- **inputs** (variadic) - Optional - Accepts any number of arguments. The backend is selected by iterating over the inputs until a backend is determined. Valid inputs include:
  - A string equal to `"numpy"` or `"pytorch"`.
  - A NumPy array (selects NumPy backend).
  - A Torch tensor (selects PyTorch backend).
  - A Backend instance (returns that instance).
  - `None` or any other value (selects NumPy backend if no other input selects a backend).

### Request Example
```python
from tslearn.backend import instantiate_backend
be = instantiate_backend("numpy")
```

### Response
#### Success Response
Returns a backend instance. The backend type can be checked via the `backend_string` attribute.

#### Response Example
```python
>>> print(be.backend_string)
"numpy"
```
```

--------------------------------

### KNeighborsTimeSeriesClassifier usage examples

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/neighbors/tslearn.neighbors.KNeighborsTimeSeriesClassifier.html

Three usage examples of KNeighborsTimeSeriesClassifier with different parameter configurations: default metric, n_jobs=2, and metric_params with itakura_max_slope. Each example fits the classifier on the same training data and predicts a query, returning array([0]).

```python
>>> clf = KNeighborsTimeSeriesClassifier(n_neighbors=2, metric="dtw")
>>> clf.fit([[1, 2, 3], [1, 1.2, 3.2], [3, 2, 1]],
...         y=[0, 0, 1]).predict([[1, 2.2, 3.5]])
array([0])
```

```python
>>> clf = KNeighborsTimeSeriesClassifier(n_neighbors=2,
...                                      metric="dtw",
...                                      n_jobs=2)
>>> clf.fit([[1, 2, 3], [1, 1.2, 3.2], [3, 2, 1]],
...         y=[0, 0, 1]).predict([[1, 2.2, 3.5]])
array([0])
```

```python
>>> clf = KNeighborsTimeSeriesClassifier(n_neighbors=2,
...                                      metric="dtw",
...                                      metric_params={
...                                          "itakura_max_slope": 2.},
...                                      n_jobs=2)
>>> clf.fit([[1, 2, 3], [1, 1.2, 3.2], [3, 2, 1]],
...         y=[0, 0, 1]).predict([[1, 2.2, 3.5]])
array([0])
```

--------------------------------

### list_univariate_datasets() example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/datasets/tslearn.datasets.UCR_UEA_datasets.html

List univariate datasets and verify the count is 128.

```python
>>> l = UCR_UEA_datasets().list_univariate_datasets()
>>> len(l)
128

```

--------------------------------

### KernelKMeans example with GAK kernel

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/clustering/tslearn.clustering.KernelKMeans.html

Shows how to instantiate and fit a KernelKMeans model using the 'gak' kernel on random walk time series, then print the unique cluster labels. The output is [0 1 2].

```python
>>> from tslearn.generators import random_walks
>>> X = random_walks(n_ts=50, sz=32, d=1)
>>> gak_km = KernelKMeans(n_clusters=3, kernel="gak", random_state=0)
>>> gak_km.fit(X)
KernelKMeans(...)
>>> print(numpy.unique(gak_km.labels_))
[0 1 2]
```

--------------------------------

### Instantiate backend with multiple inputs

Source: https://tslearn.readthedocs.io/en/stable/backend.html

instantiate_backend accepts any number of input parameters. It loops through the inputs until a backend is selected; here the Torch tensor selects the PyTorchBackend, so backend_string is "pytorch".

```python
>>> be = instantiate_backend(1, None, "Hello, World!", torch.tensor([0]), "numpy")
>>> print(be.backend_string)
"pytorch"

```

--------------------------------

### TimeSeriesSVR with GAK kernel example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/svm/tslearn.svm.TimeSeriesSVR.html

Shows how to create a TimeSeriesSVR with the 'gak' kernel and auto gamma, fit it on random walk blobs data, and inspect the prediction shape and support vectors. The output demonstrates that predictions have shape (20,) and support vectors have shape (..., 64, 2) with at most 20 support vectors.

```python
>>> from tslearn.generators import random_walk_blobs
>>> X, y = random_walk_blobs(n_ts_per_blob=10, sz=64, d=2, n_blobs=2)
>>> import numpy
>>> y = y.astype(float) + numpy.random.randn(20) * .1
>>> reg = TimeSeriesSVR(kernel="gak", gamma="auto")
>>> reg.fit(X, y).predict(X).shape
(20,)
>>> sv = reg.support_vectors_
>>> sv.shape
(..., 64, 2)
>>> sv.shape[0] <= 20
True
```

--------------------------------

### radius_neighbors example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/neighbors/tslearn.neighbors.KNeighborsTimeSeries.html

Example showing how to use radius_neighbors from sklearn.neighbors.NearestNeighbors to find neighbors within a radius. The output includes distances and indices of the neighbors.

```python
>>> import numpy as np
>>> samples = [[0., 0., 0.], [0., .5, 0.], [1., 1., .5]]
>>> from sklearn.neighbors import NearestNeighbors
>>> neigh = NearestNeighbors(radius=1.6)
>>> neigh.fit(samples)
NearestNeighbors(radius=1.6)
>>> rng = neigh.radius_neighbors([[1., 1., 1.]])
>>> print(np.asarray(rng[0][0]))
[1.5 0.5]
>>> print(np.asarray(rng[1][0]))
[1 2]
```

--------------------------------

### ts_size examples with NaN and infinity

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/utils/tslearn.utils.ts_size.html

These examples show how ts_size counts the actual size of a time series, removing trailing timesteps that are NaN across all dimensions. Infinity is considered a valid value. The examples cover 1D and 2D arrays, including cases with all-NaN trailing timesteps.

```python
>>> ts_size([1, 2, 3, numpy.nan])
3
>>> ts_size([1, numpy.nan])
1
>>> ts_size([numpy.nan])
0
>>> ts_size([[1, 2],
...          [2, 3],
...          [3, 4],
...          [numpy.nan, 2],
...          [numpy.nan, numpy.nan]])
4
>>> ts_size([numpy.nan, 3, numpy.inf, numpy.nan])
3
```

--------------------------------

### list_multivariate_datasets() example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/datasets/tslearn.datasets.UCR_UEA_datasets.html

List multivariate datasets and check that PenDigits is included.

```python
>>> l = UCR_UEA_datasets().list_multivariate_datasets()
>>> "PenDigits" in l
True

```

--------------------------------

### KShape clustering example with random_walks

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/clustering/tslearn.clustering.KShape.html

Shows how to create a synthetic dataset, scale it, fit a KShape model, and inspect the shape of the resulting cluster centers. The output (3, 32, 1) confirms the expected centroid shape for 3 clusters on 32-length univariate series.

```python
>>> from tslearn.generators import random_walks
>>> X = random_walks(n_ts=50, sz=32, d=1)
>>> X = TimeSeriesScalerMeanVariance(mu=0., std=1.).fit_transform(X)
>>> ks = KShape(n_clusters=3, n_init=1, random_state=0).fit(X)
>>> ks.cluster_centers_.shape
(3, 32, 1)
```

--------------------------------

### kneighbors_graph example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/neighbors/tslearn.neighbors.KNeighborsTimeSeries.html

Example showing how to use kneighbors_graph from sklearn.neighbors.NearestNeighbors to compute the connectivity graph of k-neighbors. The output is a CSR matrix converted to a dense array.

```python
>>> X = [[0], [3], [1]]
>>> from sklearn.neighbors import NearestNeighbors
>>> neigh = NearestNeighbors(n_neighbors=2)
>>> neigh.fit(X)
NearestNeighbors(n_neighbors=2)
>>> A = neigh.kneighbors_graph(X)
>>> A.toarray()
array([[1., 0., 1.],
       [0., 1., 1.],
       [1., 0., 1.]])
```

--------------------------------

### dtw_path example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.dtw_path.html

Compute DTW path and distance between two time series. The example shows the returned path and distance for two different inputs.

```python
>>> path, dist = dtw_path([1, 2, 3], [1., 2., 2., 3.])
>>> path
[(0, 0), (1, 1), (1, 2), (2, 3)]
>>> float(dist)
0.0
>>> float(dtw_path([1, 2, 3], [1., 2., 2., 3., 4.])[1])
1.0
```

--------------------------------

### ctw_path example with multidimensional time series

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.ctw_path.html

Compute CTW path and similarity between a univariate and a multidimensional time series. The example shows the distance value.

```python
>>> path, cca, dist = ctw_path([1, 2, 3],
...                            [[1., 1.], [2., 2.], [2., 2.], [3., 3.]])
>>> float(dist)
0.0
```

--------------------------------

### Compute sigma_gak with example dataset

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/metrics/tslearn.metrics.sigma_gak.html

Shows how to compute the sigma value for GAK using a small dataset, specifying n_samples and random_state. The output is a float representing the suggested bandwidth.

```python
>>> dataset = [[1, 2, 2, 3], [1., 2., 3., 4.]]
>>> float(sigma_gak(dataset=dataset,
...                 n_samples=200,
...                 random_state=0))
2.0...
```

--------------------------------

### Set and retrieve shapelets with LearningShapelets

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/shapelets/tslearn.shapelets.LearningShapelets.html

Shows how to create a LearningShapelets model, fit it, manually set shapelet weights, and retrieve the shapelets as a time series dataset.

```python
>>> from tslearn.generators import random_walk_blobs
>>> X, y = random_walk_blobs(n_ts_per_blob=10, sz=16, d=1, n_blobs=3)
>>> clf = LearningShapelets(n_shapelets_per_size={3: 1}, max_iter=1,
...                     verbose=0)
>>> _ = clf.fit(X, y)
>>> weights_shapelet = [
...     numpy.array([[[1], [2], [3]]])
... ]
>>> clf.set_weights(weights_shapelet, layer_name="shapelets_0")
>>> clf.shapelets_as_time_series_
array([[[1.],
        [2.],
        [3.]]])
```

--------------------------------

### NonMyopicEarlyClassifier usage example

Source: https://tslearn.readthedocs.io/en/stable/gen_modules/early_classification/tslearn.early_classification.NonMyopicEarlyClassifier.html

Demonstrates fitting the model on a small dataset, then predicting classes and earliness, and probabilities and earliness. The example shows the expected outputs for predictions and probabilities.

```python
>>> dataset = to_time_series_dataset([[1, 2, 3, 4, 5, 6],
...                                   [1, 2, 3, 4, 5, 6],
...                                   [1, 2, 3, 4, 5, 6],
...                                   [1, 2, 3, 3, 2, 1],
...                                   [1, 2, 3, 3, 2, 1],
...                                   [1, 2, 3, 3, 2, 1],
...                                   [3, 2, 1, 1, 2, 3],
...                                   [3, 2, 1, 1, 2, 3]])
>>> y = [0, 0, 0, 1, 1, 1, 0, 0]
>>> model = NonMyopicEarlyClassifier(n_clusters=3, lamb=1000.,
...                                  cost_time_parameter=.1,
...                                  random_state=0)
>>> model.fit(dataset, y)
NonMyopicEarlyClassifier(...)
>>> print(type(model.classifiers_))
<class 'dict'>
>>> print(model.pyck_)
[[0. 1. 1.]
 [1. 0. 0.]]
>>> preds, pred_times = model.predict_class_and_earliness(dataset)
>>> preds
array([0, 0, 0, 1, 1, 1, 0, 0])
>>> pred_times
array([4, 4, 4, 4, 4, 4, 1, 1])
>>> pred_probas, pred_times = model.predict_proba_and_earliness(dataset)
>>> pred_probas
array([[1., 0.],
       [1., 0.],
       [1., 0.],
       [0., 1.],
       [0., 1.],
       [0., 1.],
       [1., 0.],
       [1., 0.]])
>>> pred_times
array([4, 4, 4, 4, 4, 4, 1, 1])
```
Tokens:
Raw