Metadata-Version: 2.1
Name: eral
Version: 0.0.3
Summary: Implementation of ERAL algorithm (Stržinar et al., 2024)
Author-email: Žiga Stržinar <ziga.strzinar@ijs.si>
Project-URL: Homepage, https://repo.ijs.si/zstrzinar/eral
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: dtw-python>=1.3.0
Requires-Dist: matplotlib>=3.6.2
Requires-Dist: numpy>=1.23.4
Requires-Dist: pandas<2.0.0,>=1.4.3
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: scikit-learn>=1.2.1
Requires-Dist: scipy>=1.9.0
Requires-Dist: tslearn>=0.6.3
Requires-Dist: line-profiler>=4.1.2
Requires-Dist: numba>=0.58.1

# ERAL Algorithm

## Introduction
The ERAL (Error In Alignment) algorithm is a state-of-the-art method designed for time series alignment and averaging.
The method obtains the average time series (the prototype) from a set of time series (a class).

## Installation

To use ERAL, please clone the git repository:
```bash
git clone https://repo.ijs.si/zstrzinar/eral.git
```

The repository contains a requirements file, ensure you have all the requirements
```
pip install -r requirements.txt
```

### pip package
A pip package is being prepared and will be made available soon.

## Usage

The main entry point for the end user is `obtain_prototype` method in `eral.eral`:

```py
from src.eral.eral import obtain_prototype

class_prototype = obtain_prototype(...)
```

The function takes several arguments, most important are:
- `class_segments`: a list of time series to be aligned and averaged
- `prototyping_function`: determines how the average is computed, typically the function `get_new_prototype_variable_clipping` from `eral.alignment_prototyping_functions` can be used.
- `exclustion_zone`: percentage of forbidden alignments (see [1])

The basic function call is:

```py
import numpy as np
from src.eral.eral import obtain_prototype
from src.eral.alignment_prototyping_functions import get_new_prototype_variable_clipping

X: list[np.ndarray] = [...]  # Class data

class_prototype = obtain_prototype(X,
                                   prototyping_function=get_new_prototype_variable_clipping,
                                   exclusion_zone=0.2)
```

For full examples, please refer to the `examples/` directory.

## Examples

The `examples/` directory contains Jupyter notebooks that illustrate different uses and capabilities of the ERAL algorithm. 
To run an example, navigate to the `examples/` directory and execute the desired notebook.

- Notebook titled `01 ERAL demo` demonstrates the ERAL prototyping method using the Trace dataset from UCR Archive.
- Notebook titled `02 ERAL demo on industrial data` downloads an industrial dataset from Mendeley Data, and calculates the prototypes for all classes.
- Notebook titled `03 Comparison` compares ERAL to DBA, SSG and others, using implementations in `tslearn`


## References
[1] Paper introducing ERAL
[2] Stržinar, Žiga; Pregelj, Boštjan; Petrovčič, Janko; Škrjanc, Igor; Dolanc, Gregor (2024), “Pneumatic Pressure and Electrical Current Time Series in Manufacturing”, Mendeley Data, V2, doi: 10.17632/ypzswhhzh9.2, url: https://data.mendeley.com/datasets/ypzswhhzh9/2
