Metadata-Version: 2.1
Name: eral
Version: 0.0.5
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 install the package from pypi.org using pip:
```bash
pip install eral
```

## Usage

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

```py
from 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 eral.eral import obtain_prototype
from 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 at [our repository](https://repo.ijs.si/zstrzinar/eral).

## Demonstration
The following figure demonstrates ERAL algorithm on a set of time series from the Trace dataset from UCR Archive. The dataset contains 100 time series, each with 275 samples. The time series are aligned and averaged using ERAL, and the resulting prototype is shown in the figure.
![ERAL demonstration](docs/assets/trace-prototypes.png)


## Examples

The `examples/` directory at [our repository](https://repo.ijs.si/zstrzinar/eral) 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
