Merge pull request #2 from MSD-IRIMAS/aif/add-utils

[ENH] Add vis functions

README.md

@@ -1 +1,100 @@
-# DTW_VIS
+# 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 GIFs.
+- `utils.py`: Utility functions used in the project.
+- `config/config_hydra.yaml`: Configuration file for Hydra.
+
+
+## Usage
+
+### 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), the [regression datasets list](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tser_datasets.py) and the [forecasting datasets lists](https://github.com/aeon-toolkit/aeon/blob/main/aeon/datasets/tsf_datasets.py).
+  - `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 ItalyPowerDemand dataset
+
+- In video format: [dtw-italy](exps/dtw-vis/ItalyPowerDemand/dtw.mp4)
+- In pdf format: [dtw-italy-pdf](exps/dtw-vis/ItalyPowerDemand/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
+
+@e would like to thank the authors of the UCR, UEA and Monash archives for making the Time Series Classification/Regression/Forecasting 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.

config/config_hydra.yaml

@@ -0,0 +1,34 @@
+hydra :
+  job :
+    name : dtw-vis
+  run :
+    dir : exps/${hydra.job.name}
+
+output_dir: './'              # output directory
+dataset : "ItalyPowerDemand"            # dataset name to load from aeon
+split: Null                   # either use train/test or both splits
+znormalize: True              # znormalize each time series channel independent
+
+class_x: 0                    # In case of classification, class of first sample
+class_y: 1                    # In case of classification, class of second sample 
+
+show_warping: False           # Show warping connections in pdf
+figsize: [12,10]                 # figure size
+
+metric : "dtw"          # similarity measure to use
+metric_params :               # dictionary with measure parameters
+  window: null                # for all warping based distances
+  p : 2.0                     # for the minkowski, erp, wddtw, wdtw
+  w : null                    # for the minkowski distance
+  itakura_max_slope: null     # for all warping based distances
+  descriptor : "identity"     # for shape_dtw
+  reach : 5                  # for shape_dtw
+  g : 0.05                    # for wdtw
+  epsilon : 1.0               # for lcss, edr
+  g_arr : null                # for erp
+  nu : 0.001                  # for twe
+  lmbda : 1.0                 # for twe
+  independent : True          # for msm
+  c : 1.0                     # for msm
+  warp_penalty : 1.0          # for adtw
+  standardize : True          # for sbd