tsmotifs

tsmotifs is an open-source Python framework for time-series motif discovery. It accompanies a systematic review and benchmark project and provides a shared implementation surface for comparing motif discovery methods without replacing their original scientific definitions.

The project is intended for researchers and practitioners who need consistent algorithm interfaces, reproducible experiment execution, and common evaluation utilities across a broad and otherwise fragmented literature.

Main features

• A common MotifFinder interface and shared motif result representation.
• Integrations and reconstructions spanning several families of motif discovery methods.
• Versioned configuration, manifest generation, and runners for reproducible experiments.
• Common result serialization, aggregation, and interval-based evaluation support.

Installation

Install the core library from PyPI:

pip install tsmotifs

Some methods need additional dependencies. Install the relevant extra when required:

pip install "tsmotifs[integrations]"
pip install "tsmotifs[visualization]"
pip install "tsmotifs[deep]"

The benchmark runners and their configurations are distributed in the source repository. For benchmark reproduction or development, clone the repository and install it in editable mode:

git clone https://github.com/kdis-lab/tsmotifs.git
cd tsmotifs
python -m pip install -e ".[benchmark]"

Use python -m pip install -e ".[dev]" to include the test and release-development tools.

Quick start

The following example uses the registered MK implementation on a small series containing a repeated subsequence:

import numpy as np

from tsmotifs import MK

series = np.array(
    [0, 1, 0, -1, 0, 1, 0, -1, 2, 2, 0, 1, 0, -1],
    dtype=float,
)

finder = MK(window_size=4)
motifs = finder.fit_discover(series, top_k=1)

for motif in motifs:
    print(motif.start, motif.length, motif.matches, motif.distance)

The common interface also exposes fit() and discover() separately. Use tsmotifs.list_algorithms() to inspect the algorithms bootstrapped into the public registry.

Supported methods

The repository covers exact, approximate, symbolic, grammar-based, probabilistic, online, optimization/learning, segmentation, and deep-learning approaches. Coverage reflects the scope of the accompanying review; individual integrations can have method-specific dependencies, input constraints, or external runtime requirements.

The top-level registry is deliberately conservative so that import tsmotifs remains safe when optional dependencies are absent. The benchmark configuration under experiment/config/ is the source of truth for methods used in each experimental phase.

Reproducibility

The experiment/ tree contains the versioned configurations, manifest builders, execution runners, aggregation code, and Slurm support used by the review benchmark. See the experimental pipeline and the HPC runbook before reproducing experiments.

Benchmark datasets and generated results are intentionally not part of the PyPI wheel. A link to the companion project website and the paper's final bibliographic record will be added when they are public; until then, this repository is the canonical supporting software artifact.

Citation

If you use tsmotifs, cite the associated review paper once its bibliographic record is available and cite the software version used in your experiments. Machine-readable software citation metadata is provided in CITATION.cff.

Contributing

Bug reports, documentation improvements, packaging fixes, and carefully scoped algorithm integrations are welcome. Please read CONTRIBUTING.md before opening an issue or pull request. Changes that affect taxonomy, evaluation methodology, or benchmark protocols require explicit scientific review.

License

tsmotifs is distributed under the BSD 3-Clause License.