Welcome to TSMD’s documentation!

Overview

The TSMD project brings together Motif Discovery methods for Time Series, aiming to compare their performance through well-defined research questions and to simplify their practical use. It provides both guidelines for selecting the most suitable methods based on the data, and accessible implementations of the most relevant approaches.

Installation

Install tsmd with pip

You can install tsmd using pip:

pip install tsmd

Install tsmd from source

The following tools are required to install TSMD from source:

  • git

  • conda (anaconda or miniconda)

Clone this repository using git and go into its root directory.

git clone https://github.com/grrvlr/TSMD.git
cd TSMD/

Create and activate a conda-environment ‘TSMD’.

conda env create --file environment.yml
conda activate TSMD

Usage

We depicts below a code snippet demonstrating how to use one motif detection algorithm (in this example, we first generate a synthetic time series).

from tsmd.tools.synthetic_signal import SignalGenerator

generator=SignalGenerator(n_motifs=2, motif_length=200, motif_amplitude=3, motif_fundamental=3, sparsity=0.5, sparsity_fluctuation=0.5)
signal,labels= generator.generate()
generator.plot()
Synthetic signal 
from tsmd.competitors.persistence import BasePersistentPattern
from tsmd.tools.utils import transform_label
from tsmd.tools.plotting import plot_signal_pattern


pepa=BasePersistentPattern(wlen_for_persistence=180, n_patterns=2)
pepa.fit(signal)
labels=transform_label(pepa.prediction_mask_)
plot_signal_pattern(signal,labels)
PEPA output

License

The project is licensed under the MIT license.

If you use TSMD in your project or research, please cite the following paper:

Time Series Motif Discovery: A Comprehensive Evaluation Valerio Guerrini, Thibaut Germain, Charles Truong, Laurent Oudre, Paul Boniol. Proceedings of the VLDB Endowment (PVLDB 2025) Journal, Volume 18.

You can use the following BibTeX entries:

@article{Guerrini2025tsmd,
   title={Time Series Motif Discovery: A Comprehensive Evaluation},
   author={Guerrini, Valerio and Germain, Thibaut and Truong, Charles and Oudre, Laurent and Boniol, Paul},
   journal={Proceedings of the VLDB Endowment},
   volume={18},
   number={7},
   year={2025},
   publisher={VLDB Endowment}
}

Contributors

  • Valerio Guerrini (Centre Borelli, ENS Paris Saclay, Université Paris Cité)

  • Thibaut Germain (Centre Borelli, ENS Paris Saclay, Université Paris Cité)

  • Charles Truong (Centre Borelli, ENS Paris Saclay, Université Paris Cité)

  • Laurent Oudre (Centre Borelli, ENS Paris Saclay, Université Paris Cité)

  • Paul Boniol (Inria, ENS, CNRS, PSL University)