# 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
### pip package

To use ERAL, please install the package from pypi.org using pip:
```bash
pip install eral
```

### From source
To access ERAL source code, 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
```

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