Metadata-Version: 2.4
Name: tsmotifs
Version: 0.1.1
Summary: Research framework for time-series motif discovery, review, and benchmarking
Author: Christian Luna
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/kdis-lab/tsmotifs
Project-URL: Repository, https://github.com/kdis-lab/tsmotifs.git
Project-URL: Issues, https://github.com/kdis-lab/tsmotifs/issues
Project-URL: Changelog, https://github.com/kdis-lab/tsmotifs/blob/main/CHANGELOG.md
Keywords: time series,motif discovery,data mining,benchmark,reproducible research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: scipy<1.16,>=1.15
Requires-Dist: pandas<2.4,>=2.3
Requires-Dist: scikit-learn<1.7,>=1.6
Requires-Dist: numba<0.62,>=0.61
Requires-Dist: joblib<1.6,>=1.5
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: tqdm<5.0,>=4.67
Requires-Dist: networkx<4.0,>=3.5
Requires-Dist: bitarray<4.0,>=3.7
Requires-Dist: sortedcontainers<3.0,>=2.4
Provides-Extra: integrations
Requires-Dist: aeon==1.2.0; extra == "integrations"
Requires-Dist: dtaidistance<2.5,>=2.4; extra == "integrations"
Requires-Dist: dtcwt<0.15,>=0.14; extra == "integrations"
Requires-Dist: fastdtw==0.3.4; extra == "integrations"
Requires-Dist: hmmlearn<0.4,>=0.3.3; extra == "integrations"
Requires-Dist: ortools<9.11,>=9.10; extra == "integrations"
Requires-Dist: pyattimo==0.8.1; extra == "integrations"
Requires-Dist: pyscamp<5.0,>=4.0; extra == "integrations"
Requires-Dist: PyWavelets<2.0,>=1.9; extra == "integrations"
Requires-Dist: saxpy==1.0.1.dev167; extra == "integrations"
Requires-Dist: statsmodels<0.15,>=0.14.6; extra == "integrations"
Provides-Extra: visualization
Requires-Dist: matplotlib<3.11,>=3.10; extra == "visualization"
Requires-Dist: seaborn<0.14,>=0.13; extra == "visualization"
Requires-Dist: plotly<7.0,>=6.2; extra == "visualization"
Requires-Dist: Pillow<13.0,>=12.2; extra == "visualization"
Requires-Dist: tsdownsample<0.2,>=0.1.4; extra == "visualization"
Provides-Extra: deep
Requires-Dist: tensorflow==2.19.0; extra == "deep"
Requires-Dist: keras<3.15,>=3.14; extra == "deep"
Requires-Dist: h5py<4.0,>=3.16; extra == "deep"
Requires-Dist: Pillow<13.0,>=12.2; extra == "deep"
Provides-Extra: benchmark
Requires-Dist: tsmotifs[deep,integrations,visualization]; extra == "benchmark"
Requires-Dist: optuna==4.4.0; extra == "benchmark"
Requires-Dist: psutil<8.0,>=7.0; extra == "benchmark"
Requires-Dist: memory-profiler==0.61.0; extra == "benchmark"
Provides-Extra: test
Requires-Dist: pytest<9.0,>=8.4; extra == "test"
Requires-Dist: pytest-cov<8.0,>=7.0; extra == "test"
Provides-Extra: dev
Requires-Dist: tsmotifs[test]; extra == "dev"
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: twine<8.0,>=6.0; extra == "dev"
Provides-Extra: experiments
Requires-Dist: tsmotifs[benchmark]; extra == "experiments"
Provides-Extra: viz
Requires-Dist: tsmotifs[visualization]; extra == "viz"
Provides-Extra: all
Requires-Dist: tsmotifs[benchmark,test]; extra == "all"
Dynamic: license-file

# 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:

```bash
pip install tsmotifs
```

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

```bash
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:

```bash
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:

```python
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](https://github.com/kdis-lab/tsmotifs/blob/main/experiment/README_experiments.md) and [the HPC runbook](https://github.com/kdis-lab/tsmotifs/blob/main/experiment/README_hpc_phase1.md) 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`](https://github.com/kdis-lab/tsmotifs/blob/main/CITATION.cff).

## Contributing

Bug reports, documentation improvements, packaging fixes, and carefully scoped algorithm integrations are welcome. Please read [`CONTRIBUTING.md`](https://github.com/kdis-lab/tsmotifs/blob/main/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](https://github.com/kdis-lab/tsmotifs/blob/main/LICENSE).
