# Elastic Warping Visualization For Time Series
## Author
- **Ali Ismail-Fawaz** ([hadifawaz1999](https://github.com/hadifawaz1999))
This repository contains a project for visualizing warping distortions such as the ones produced by Dynamic Time Warping (DTW) between two time series. The project includes functions to generate plots and animated MP4s showcasing the alignment between the series. The repository is configured using [Hydra](https://hydra.cc/docs/intro/) for flexible and organized parameter management, and [aeon-toolkit](https://www.aeon-toolkit.org/en/stable/) for all time series processing and similarity measure calculation.
## Contents
- `main.py`: The main script to run the DTW visualization.
- `draw_functions.py`: Contains the functions for generating plots and MP4s.
- `utils.py`: Utility functions used in the project.
- `config/config_hydra.yaml`: Configuration file for Hydra.
## Usage
### PyPi Package
Simply install the package as such `pip install elastic_warping_vis`, latest version being `0.2.0` and then use it as follows:
```Python
from elastic_warping_vis.utils import load_data
from elastic_warping_vis.draw_functions import draw_elastic_gif, draw_elastic
# ignore third output, used for dev version
X, y, _ = load_data(dataset_name="ECG200", split="train", znormalize=True)
ts1 = X[y == 0][0]
ts2 = X[y == 1][0]
draw_elastic(ts1, ts2, metric="dtw")
draw_elastic_gif(ts1, ts2, metric="dtw")
```
### Prerequisites
- Python >= 3.10
- Required Python libraries:
- `numpy==1.26.4`
- `matplotlib==3.9.0`
- `hydra-core==1.3.2`
- `aeon==0.10.0`
- Required on the system:
- `ffmpeg` version `4.4.2`
### Running the Code
1. Configure the parameters in `config/config_hydra.yaml` as needed.
2. Run the main script:
```sh
python3 main.py
```
### Configuration Parameters
The following parameters can be configured in the `config/config_hydra.yaml` file:
- **Hydra Configuration:**
- `hydra.job.name`: Name of the job (default: `dtw-vis`).
- `hydra.run.dir`: Directory to save experiment results (default: `exps/${hydra.job.name}`).
- **General Parameters:**
- `output_dir`: Directory where output plots and MP4s will be saved (default: `./`).
- `dataset`: Name of the dataset to use (default: `ItalyPowerDemand`) loaded from aeon-toolkit, see the [classification dataset list](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tsc_datasets.py) and the [regression datasets list](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tser_datasets.py), works with both univariate and multivariate time series datasets.
- `split`: Dataset split (default: `None`).
- `znormalize`: Whether to Z-normalize the time series (default: `True`).
- `class_x`: Class label for the first time series (default: `0`).
- `class_y`: Class label for the second time series (default: `1`).
- `show_warping`: Whether to show warping connections in the plot (default: `False`).
- `figsize`: Figure size for the plots (default: `[12, 10]`).
- **Metric Parameters:**
- `metric`: Metric used for elastic warping calculation (default: `dtw`), see [aeon's list of elastic measures](https://www.aeon-toolkit.org/en/stable/api_reference/distances.html).
- `metric_params`: Additional parameters for the DTW metric, including:
- `window`: Window size for the Sakoe-Chiba band (default: `None`).
- `p`: Parameter for p-norm (default: `2.0`).
- `w`: Window size (default: `None`).
- `itakura_max_slope`: Maximum slope for Itakura parallelogram (default: `None`).
- `descriptor`: Descriptor function (default: `identity`).
- `reach`: Reach parameter (default: `5`).
- `g`: Parameter for derivative DTW (default: `0.05`).
- `epsilon`: Epsilon parameter for soft-DTW (default: `1.0`).
- `g_arr`: G array for derivative DTW (default: `None`).
- `nu`: Regularization parameter for shape-based DTW (default: `0.001`).
- `lmbda`: Regularization parameter for penalized DTW (default: `1.0`).
- `independent`: Whether to use independent feature DTW (default: `True`).
- `c`: Regularization parameter for elastic shape DTW (default: `1.0`).
- `warp_penalty`: Penalty for warping path length (default: `1.0`).
- `standardize`: Whether to standardize the time series before DTW (default: `True`).
<!-- ## Example
Using DTW on [ECGFiveDays](http://timeseriesclassification.com/description.php?Dataset=ECGFiveDays) univariate dataset
- In video format [download-here](exps/dtw-vis/ECGFiveDays/dtw.mp4): 
- In pdf format: [dtw-italy-pdf](exps/dtw-vis/ECGFiveDays/dtw.pdf)
Using DTW on [ERing](http://timeseriesclassification.com/description.php?Dataset=ERing) multivariate dataset
- In video format [download-here](exps/dtw-vis/ERing/dtw.mp4): 
- In pdf format: [dtw-italy-pdf](exps/dtw-vis/ERing/dtw.pdf) -->
## Citation
If you use this code in your research, please cite this repository:
```bibtex
@misc{ismail-fawaz2024elastic-vis,
author = {Ismail-Fawaz, Ali and Devanne, Maxime and Berretti, Stefano and Weber, Jonathan and Forestier, Germain},
title = {Elastic Warping Visualization For Time Series},
year = {2024},
publisher = {Github},
journal = {GitHub repository},
howpublished = {\url{https://github.com/yourusername/dtw-visualization}}
}
```
## Acknowledgments
We would like to thank the authors of the UCR, UEA and Monash archives for making the Time Series Classification/Regression datasets publicly available.
We would also like to thank the Aeon time series machine learning python toolkit for their fast implementation of elastic similarity measures.
Raw data
{
"_id": null,
"home_page": null,
"name": "elastic-warping-vis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Ali Ismail-Fawaz <ali-el-hadi.ismail-fawaz@uha.fr>",
"keywords": "data-science, machine-learning, data-mining, time-series, dynamic-time-warping, elastic-similarity-measures, elastic-distances, time-series-analysis, time-series-classification, time-series-regression, time-series-machine-learning, data-visualization",
"author": null,
"author_email": "Ali Ismail-Fawaz <ali-el-hadi.ismail-fawaz@uha.fr>, Maxime Devanne <maxime.devanne@uha.fr>, Stefano Berretti <stefano.berretti@unifi.it>, Jonathan Weber <jonathan.weber@uha.fr>, Germain Forestier <germain.forestier@uha.fr>",
"download_url": "https://files.pythonhosted.org/packages/e5/f1/e607cbdeec82c05a6a64144cb690242060afbdb91453d8bb278873efc876/elastic_warping_vis-0.2.1.tar.gz",
"platform": null,
"description": "# Elastic Warping Visualization For Time Series\n\n## Author\n\n- **Ali Ismail-Fawaz** ([hadifawaz1999](https://github.com/hadifawaz1999))\n\nThis repository contains a project for visualizing warping distortions such as the ones produced by Dynamic Time Warping (DTW) between two time series. The project includes functions to generate plots and animated MP4s showcasing the alignment between the series. The repository is configured using [Hydra](https://hydra.cc/docs/intro/) for flexible and organized parameter management, and [aeon-toolkit](https://www.aeon-toolkit.org/en/stable/) for all time series processing and similarity measure calculation.\n\n## Contents\n\n- `main.py`: The main script to run the DTW visualization.\n- `draw_functions.py`: Contains the functions for generating plots and MP4s.\n- `utils.py`: Utility functions used in the project.\n- `config/config_hydra.yaml`: Configuration file for Hydra.\n\n\n## Usage\n\n### PyPi Package\n\nSimply install the package as such `pip install elastic_warping_vis`, latest version being `0.2.0` and then use it as follows:\n```Python\nfrom elastic_warping_vis.utils import load_data\nfrom elastic_warping_vis.draw_functions import draw_elastic_gif, draw_elastic\n\n# ignore third output, used for dev version\nX, y, _ = load_data(dataset_name=\"ECG200\", split=\"train\", znormalize=True)\n\nts1 = X[y == 0][0]\nts2 = X[y == 1][0]\ndraw_elastic(ts1, ts2, metric=\"dtw\")\ndraw_elastic_gif(ts1, ts2, metric=\"dtw\")\n\n```\n\n### Prerequisites\n\n- Python >= 3.10\n- Required Python libraries:\n - `numpy==1.26.4`\n - `matplotlib==3.9.0`\n - `hydra-core==1.3.2`\n - `aeon==0.10.0`\n- Required on the system:\n - `ffmpeg` version `4.4.2`\n\n### Running the Code\n\n1. Configure the parameters in `config/config_hydra.yaml` as needed.\n2. Run the main script:\n ```sh\n python3 main.py\n ```\n\n### Configuration Parameters\n\nThe following parameters can be configured in the `config/config_hydra.yaml` file:\n\n- **Hydra Configuration:**\n - `hydra.job.name`: Name of the job (default: `dtw-vis`).\n - `hydra.run.dir`: Directory to save experiment results (default: `exps/${hydra.job.name}`).\n\n- **General Parameters:**\n - `output_dir`: Directory where output plots and MP4s will be saved (default: `./`).\n - `dataset`: Name of the dataset to use (default: `ItalyPowerDemand`) loaded from aeon-toolkit, see the [classification dataset list](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tsc_datasets.py) and the [regression datasets list](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tser_datasets.py), works with both univariate and multivariate time series datasets.\n - `split`: Dataset split (default: `None`).\n - `znormalize`: Whether to Z-normalize the time series (default: `True`).\n - `class_x`: Class label for the first time series (default: `0`).\n - `class_y`: Class label for the second time series (default: `1`).\n - `show_warping`: Whether to show warping connections in the plot (default: `False`).\n - `figsize`: Figure size for the plots (default: `[12, 10]`).\n\n- **Metric Parameters:**\n - `metric`: Metric used for elastic warping calculation (default: `dtw`), see [aeon's list of elastic measures](https://www.aeon-toolkit.org/en/stable/api_reference/distances.html).\n - `metric_params`: Additional parameters for the DTW metric, including:\n - `window`: Window size for the Sakoe-Chiba band (default: `None`).\n - `p`: Parameter for p-norm (default: `2.0`).\n - `w`: Window size (default: `None`).\n - `itakura_max_slope`: Maximum slope for Itakura parallelogram (default: `None`).\n - `descriptor`: Descriptor function (default: `identity`).\n - `reach`: Reach parameter (default: `5`).\n - `g`: Parameter for derivative DTW (default: `0.05`).\n - `epsilon`: Epsilon parameter for soft-DTW (default: `1.0`).\n - `g_arr`: G array for derivative DTW (default: `None`).\n - `nu`: Regularization parameter for shape-based DTW (default: `0.001`).\n - `lmbda`: Regularization parameter for penalized DTW (default: `1.0`).\n - `independent`: Whether to use independent feature DTW (default: `True`).\n - `c`: Regularization parameter for elastic shape DTW (default: `1.0`).\n - `warp_penalty`: Penalty for warping path length (default: `1.0`).\n - `standardize`: Whether to standardize the time series before DTW (default: `True`).\n\n<!-- ## Example\n\nUsing DTW on [ECGFiveDays](http://timeseriesclassification.com/description.php?Dataset=ECGFiveDays) univariate dataset\n\n- In video format [download-here](exps/dtw-vis/ECGFiveDays/dtw.mp4): \n- In pdf format: [dtw-italy-pdf](exps/dtw-vis/ECGFiveDays/dtw.pdf)\n\nUsing DTW on [ERing](http://timeseriesclassification.com/description.php?Dataset=ERing) multivariate dataset\n\n- In video format [download-here](exps/dtw-vis/ERing/dtw.mp4): \n- In pdf format: [dtw-italy-pdf](exps/dtw-vis/ERing/dtw.pdf) -->\n\n## Citation\n\nIf you use this code in your research, please cite this repository:\n\n```bibtex\n@misc{ismail-fawaz2024elastic-vis,\n author = {Ismail-Fawaz, Ali and Devanne, Maxime and Berretti, Stefano and Weber, Jonathan and Forestier, Germain},\n title = {Elastic Warping Visualization For Time Series},\n year = {2024},\n publisher = {Github},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/yourusername/dtw-visualization}}\n}\n```\n\n## Acknowledgments\n\nWe would like to thank the authors of the UCR, UEA and Monash archives for making the Time Series Classification/Regression datasets publicly available.\nWe would also like to thank the Aeon time series machine learning python toolkit for their fast implementation of elastic similarity measures.\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Visualization of Elastic Warping of Time Series Data",
"version": "0.2.1",
"project_urls": null,
"split_keywords": [
"data-science",
" machine-learning",
" data-mining",
" time-series",
" dynamic-time-warping",
" elastic-similarity-measures",
" elastic-distances",
" time-series-analysis",
" time-series-classification",
" time-series-regression",
" time-series-machine-learning",
" data-visualization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d36f0d254e23d40c05a919f517b6d5457b3160b8f8e2e58316c8b5e4a233c61",
"md5": "ff11375bf9d6aa5ae6956f9f6b18b6c4",
"sha256": "2263111d00a9c122ee8f8426fa3a1688f8ed02effd69cec8b16af60c154bd65e"
},
"downloads": -1,
"filename": "elastic_warping_vis-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff11375bf9d6aa5ae6956f9f6b18b6c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 20136,
"upload_time": "2024-07-29T16:59:02",
"upload_time_iso_8601": "2024-07-29T16:59:02.037017Z",
"url": "https://files.pythonhosted.org/packages/5d/36/f0d254e23d40c05a919f517b6d5457b3160b8f8e2e58316c8b5e4a233c61/elastic_warping_vis-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5f1e607cbdeec82c05a6a64144cb690242060afbdb91453d8bb278873efc876",
"md5": "4044dddf7df94bf30ea9e99af81af12a",
"sha256": "56d213f0ac49fce4ace2c43dca7066cc153baa8e95e66caf15df9bd5c1d775fb"
},
"downloads": -1,
"filename": "elastic_warping_vis-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4044dddf7df94bf30ea9e99af81af12a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 2039707,
"upload_time": "2024-07-29T16:59:03",
"upload_time_iso_8601": "2024-07-29T16:59:03.914251Z",
"url": "https://files.pythonhosted.org/packages/e5/f1/e607cbdeec82c05a6a64144cb690242060afbdb91453d8bb278873efc876/elastic_warping_vis-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 16:59:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "elastic-warping-vis"
}
JSON