Metadata-Version: 2.4
Name: tsmorph
Version: 0.3.0
Summary: A package for generating semi-synthetic time series using morphing techniques.
Author: Moisés Santos
License-Expression: GPL-3.0-only
Project-URL: homepage, https://github.com/moisesrsantos/tsmorph
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: pycatch22
Requires-Dist: neuralforecast
Provides-Extra: ete-ts
Requires-Dist: ete_ts; extra == "ete-ts"
Dynamic: license-file

# tsMorph

tsMorph is a Python package designed to generate semi-synthetic time series through morphing techniques. It enables the systematic transformation between two given time series, facilitating robust performance evaluation of forecasting models.

This package is based on the paper:  
**Santos, M., de Carvalho, A., & Soares, C. (2024).** *Enhancing Algorithm Performance Understanding through tsMorph: Generating Semi-Synthetic Time Series for Robust Forecasting Evaluation.* [arXiv:2312.01344](https://arxiv.org/abs/2312.01344)

## Features
- **Generation of Semi-Synthetic Time Series**: Creates a set of intermediate time series transitioning from a source series (S) to a target series (T).
- **Performance Understanding**: Evaluates forecasting models' robustness using MASE (Mean Absolute Scaled Error) over synthetic series.
- **Feature Extraction**: Uses `pycatch22` to extract time series features for deeper analysis.
- **Visualization Tools**: Provides plotting functions to explore synthetic time series and their performance.

## Installation

```bash
pip install tsmorph
```

## Usage

### Generate Semi-Synthetic Time Series

```python
import numpy as np
import pandas as pd
from tsmorph import TSmorph

# Define source and target time series
S = np.array([1, 2, 3, 4, 5])
T = np.array([6, 7, 8, 9, 10])

ts_morph = TSmorph(S, T, granularity=5)
synthetic_df = ts_morph.fit()
print(synthetic_df)
```

### Plot Semi-Synthetic Time Series

```python
ts_morph.plot(synthetic_df)
```

### Performance Understanding with Forecasting Models

```python
from some_forecasting_model import TrainedModel

# Assume a trained forecasting model compatible with NeuralForecast
model = TrainedModel()

# Define forecast horizon
horizon = 2

# Analyze performance over synthetic series
ts_morph.analyze_morph_performance(synthetic_df, model, horizon)
```

## Citation
If you use `tsMorph` in your research, please cite:

```bibtex
@article{santos2024tsmorph,
  title={Enhancing Algorithm Performance Understanding through tsMorph: Generating Semi-Synthetic Time Series for Robust Forecasting Evaluation},
  author={Santos, Mois{\'e}s and de Carvalho, Andr{\'e} and Soares, Carlos},
  journal={arXiv preprint arXiv:2312.01344},
  year={2024}
}
```
---

## License
This project is licensed under the GNU General Public License v3.0.

## Funding information

Agenda “Center for Responsible AI”, nr. C645008882-00000055, investment project nr. 62, financed by the Recovery and Resilience Plan (PRR) and by European Union -  NextGeneration EU.

AISym4Med (101095387) supported by Horizon Europe Cluster 1: Health, ConnectedHealth (n.o 46858), supported by Competitiveness and Internationalisation Operational Programme (POCI) and Lisbon Regional Operational Programme (LISBOA 2020), under the PORTUGAL 2020 Partnership Agreement, through the European Regional Development Fund (ERDF)
