LoCoMotif: Discovering time-warped motifs in time series

This repository contains the implementation of LoCoMotif, a method for time series motif discovery (TSMD). LoCoMotif stands out from existing methods as it can detect variable-length motifs (motifs of different durations), time-warped motifs (with slight temporal misalignments, as handled by Dynamic Time Warping), and multivariate motifs (spanning multiple dimensions). It was introduced in this publication.

🛤️ Installation

The easiest way to install is to use pip.

Install using pip

pip install dtai-locomotif

You can also install from source.

Build from source

First, clone the repository:

git clone https://github.com/ML-KULeuven/locomotif.git

Then, navigate into the directory and build the package from source:

pip install .

🚂 Usage

A time series is representated as 2d numpy array of shape (n, d) where n is the length of the time series and d the number of dimensions:

f = open(os.path.join("..", "examples", "datasets", "mitdb_patient214.csv"))
ts = np.array([line.split(',') for line in f.readlines()], dtype=np.double)

print(ts.shape)
>>> (3600, 2)

To apply LoCoMotif to the time series, simply import the locomotif module and call the apply_locomotif method with suitable parameter values. Note that, we highly advise you to first z-normalize the time series.

import locomotif.locomotif as locomotif 
ts = (ts - np.mean(ts, axis=None)) / np.std(ts, axis=None)
motif_sets = locomotif.apply_locomotif(ts, l_min=216, l_max=360, rho=0.6)

The parameters l_min and l_max respectively represent the minimum and maximum motif length of the representative of a motif set. The parameter rho determines the ''strictness'' of the LoCoMotif method; or in other words, how similar the subsequences in a motif set are expected to be. The best value of rho depends heavily on the application; however, in most of our experiments, a value between 0.6 and 0.8 always works relatively well.
Optionally, we allow you to choose the allowed overlap between motifs through the overlap parameter (which lies between 0.0 and 0.5), the number of motif sets to be discovered through the nb parameter (by default, nb=None and LoCoMotif finds all motifs), and whether to use time warping or not through the warping parameter (either True or False)

The result of LoCoMotif is a list of (candidate, motif_set) tuples, where each candidate is the representative subsequence (the most "central" subsequence) of the corresponding motif_set. Each candidate is a tuple of two integers (b, e) representing the start- and endpoint of the corresponding time segment, while each motif_set is a list of such tuples.

print(motif_sets)
>>> [((2666, 2931), [(2666, 2931), (1892, 2136), (1038, 1332), (2334, 2665), (628, 1035), (1589, 1892), (1, 260)]), ((2931, 3155), [(2931, 3155), (2136, 2333), (1332, 1558)])]

We also include a visualization module, visualize, to plot the time series together with the found motifs:

import locomotif.visualize as visualize
import matplotlib.pyplot as plt

fig, ax = visualize.plot_motif_sets(ts, motif_sets)
plt.show()

More examples can be found in this folder.

📃 License

This project is licensed under the MIT License - see the LICENSE file for details.