Metadata-Version: 2.1
Name: abimca
Version: 0.2.5
Summary: Autoencoder based iterative modeling and multivariate time-series subsequence clustering algorithm (ABIMCA)
Home-page: https://github.com/Jokonu/abimca
License: BSD-3-Clause
Keywords: time-series,multivariate,autoencoder,subsequence,identification,clustering,algorithm
Author: Jonas Köhne
Author-email: jokohonas@gmail.com
Maintainer: Jonas Köhne
Maintainer-email: jokohonas@gmail.com
Requires-Python: >=3.9,<3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Scientific/Engineering
Requires-Dist: coloredlogs (>=15.0.1,<16.0.0)
Requires-Dist: matplotlib (>=3.5.3,<4.0.0)
Requires-Dist: numpy (>=1.23.2,<2.0.0)
Requires-Dist: pandas (>=1.4.3,<2.0.0)
Requires-Dist: scikit-learn (>=1.1.2,<2.0.0)
Requires-Dist: scipy (>=1.9.0,<2.0.0)
Requires-Dist: torch (>=1.12.1,<2.0.0)
Requires-Dist: tqdm (>=4.64.0,<5.0.0)
Project-URL: Repository, https://github.com/Jokonu/abimca
Description-Content-Type: text/markdown

[![DOI](https://zenodo.org/badge/529262007.svg)](https://zenodo.org/badge/latestdoi/529262007) [![Python 3.9](https://img.shields.io/badge/Python-3.9-blue)](https://www.python.org/downloads/release/python-390/)

# Autoencoder Based Iterative Modeling and Subsequence Clustering Algorithm (ABIMCA)

This repository contains the python code for the Autoencoder Based Iterative Modeling and Subsequence Clustering Algorithm (ABIMCA)[^koehn] which is a deep learning method to separate multivariate time-series data (MTSD) into subsequences. It is beneficial in a variety of fields, to cluster MTSD into smaller segments or subsequences in an unsupervised manner. The ability to filter measurement data based on specific subsequences can improve downstream development products such as anomaly detection or machine diagnosis in condition based maintenance (CbM) strategies. Our algorithm is specifically useful for MTSD generated by a mechatronic system in a transient environment. It can be used offline as well as online for streaming data. It utilizes recurrent neural network (RNN) based Autoencoders (AE) by iteratively training a Base Autoencoder (BAE), generating a segmentation score and saving the intermediate parameters of the BAE to recognize previously identified subsequences.

![Autoencoder Based Iterative Modeling and Subsequence Clustering Algorithm (ABIMCA)](abimca.gif)

# Usage

Package can be installed with pip

```bash
$ pip install abimca
```

or clone the repository, and cd into the directory. Then recommendation is to create a virtual environment after installing and using python 3.9 with [pyenv](https://github.com/pyenv/pyenv)

```python
python -m venv .venv
```
activate the environment
Linux:
    $ source .venv/bin/activate

Windows cmd:
    C:\> .venv\Scripts\activate.bat

Then install with [poetry](https://python-poetry.org/)

```bash
$ poetry install
```

Finally run the minimal example in *main.py*

```bash
$ python -m main
```

The above graphic example was generated with the *run_lorenz.py* script. The minimal example is as follows:

```python
from abimca import SubsequenceIdentifier
import numpy as np


def main():
    # Generating random data. This will produce no class predictions or all points have the same class. For more reasonable results replace the data input with your mechatronic measurement data.
    # Number of datapoints (time-steps)
    n_p = 300
    # Number of dimensions or features
    dim = 5
    X = np.random.rand(n_p, dim)
    # Number of clusters
    n_c = 5
    y = np.random.randint(n_c, size=n_p)

    # Compute online clustering
    si = SubsequenceIdentifier(disable_progress_bar=False)
    si.fit(X)
    print(f"Label array from online fitting: \n{si.label_array}")

    # Compute offline clustering
    labels = si.predict(X)
    print(f"Label array from online fitting: \n{labels}")


if __name__ == "__main__":
    main()
```

## References
[^koehn]: Köhne, J. et al. Autoencoder based iterative modeling and multivariate time-series subsequence clustering algorithm

