tsururu - GitLite

KO | EN

gitlite — search

#windows #open-source #sql #pytorch #typescript #nextjs #deep-learning #c #java #cli

tsururu

(★ 231)

Tsururu is a Python-based library that provides a wide range of multi-series and multi-point-ahead prediction strategies, compatible with any underlying model, including neural networks.

File Explorer

ZIP Download

- - bug_report.md
  - feature_request.md
- - ci.yml
- - demand_forecasting_kernels.csv
  - simulated_data_to_check.csv
  - simulated_data_to_check_28D.csv
- - alternative_aggregations.ipynb
  - clean_results.ipynb
  - results_normalized_True_cleaned.csv
- - CD_ILI.png
- - run_all.sh
  - run_exp.py
- - validation.py
- Example_1_All_configurations.py
- README.md
- Tutorial_1_Quick_start.ipynb
- Tutorial_2_Strategies.ipynb
- Tutorial_3_Transformers_and_Pipeline.ipynb
- Tutorial_4_Neural_Networks.ipynb
- direct.png
- flatwidemimo.png
- global.png
- local.png
- mimo.png
- multivariate.png
- recursive.png
- time_series.png
- time_series_example.png
- tsururu_logo.png
- - test_different_freqs.py
- - test_ml.py
  - test_nn.py
- - conftest.py
  - test_categorical_encoding.py
  - test_output_features.py
  - test_X_with_from_target_date.py
  - test_X_y_with_different_transformers_for_flatwidemimo.py
- - test_fwm.py
- - __init__.py
  - dataset.py
  - pipeline.py
  - slice.py
- - __init__.py
  - trainer.py
  - validator.py
- - __init__.py
  - boost.py
  - ml_base.py
- - __init__.py
  - base.py
  - direct.py
  - flat_wide_mimo.py
  - mimo.py
  - recursive.py
  - utils.py
- - __init__.py
  - base.py
  - categorical.py
  - datetime.py
  - impute.py
  - numeric.py
  - seq.py
  - utils.py
- - __init__.py
  - logging.py
  - optional_imports.py
- __init__.py
.gitignore
.pre-commit-config.yaml
CONTRIBUTING.md
LICENSE
pyproject.toml
README.md
uv.lock

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![tsururu_logo](https://raw.githubusercontent.com/sb-ai-lab/tsururu/main/imgs/tsururu_logo.png)

Tsururu is a Python-based library that provides a wide range of multi-series and multi-point-ahead prediction strategies, compatible with any underlying model, including neural networks.

While much attention is currently focused on selecting models for time series forecasting, the crucial aspect of how to perform training and inference often goes overlooked. Tsururu aims to address this gap.

Also tsururu provides various preprocessing techniques.

🎉 `Accepted to the Demo-Track of IJCAI 2025` — Results and code can be found in `examples`.

<a name="quicktour"></a>
## Quick tour

```python
from tsururu.dataset import Pipeline, TSDataset
from tsururu.model_training.trainer import MLTrainer
from tsururu.model_training.validator import KFoldCrossValidator
from tsururu.models.boost import CatBoost
from tsururu.strategies import RecursiveStrategy

dataset_params = {
    "target": {"columns": ["value"]},
    "date": {"columns": ["date"]},
    "id": {"columns": ["id"]},
}

dataset = TSDataset(
    data=pd.read_csv(df_path),
    columns_params=dataset_params,
)

pipeline = Pipeline.easy_setup(
    dataset_params, {"target_lags": 3, "date_lags": 1}, multivariate=False
)
trainer = MLTrainer(model=CatBoost, validator=KFoldCrossValidator)
strategy = RecursiveStrategy(horizon=3, history=7, trainer=trainer, pipeline=pipeline)

fit_time, _ = strategy.fit(dataset)
forecast_time, current_pred = strategy.predict(dataset)
```

<a name="installation"></a>
## Installation
To install Tsururu on your machine from PyPI:
```bash
# Base functionality (it's recommended to install at least one addition dependency with models):
pip install -U tsururu

# For partial installation use corresponding option
# Extra dependencies: [catboost, torch, pyboost] or use 'all' to install all dependencies
pip install -U tsururu[catboost]
```

<a name="examples"></a>
## Other tutorials and examples

* [Tutorial_1_Quick_Start](https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb) for simple usage examples
* [Tutorial_2_Strategies](https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb) covers forecasting strategies.
* [Tutorial_3_Transformers_and_Pipeline](https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_3_Transformers_and_Pipeline.ipynb) provides a description of available data preprocessing techniques.
* [Tutorial_4_Neural_Networks](https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb) demonstrates working with neural networks.
* [Example_1_All_configurations](https://github.com/sb-ai-lab/tsururu/blob/main/examples/Example_1_All_configurations.py) script for benchmarking multiple configurations from available strategies, models and preprocessing methods on a dataset.
* [Demo_1_Tourism_Monthly_Dataset](https://www.kaggle.com/code/elineii/tsururu-demo).

<a name="description"></a>
## Multi-series prediction strategies:
- _Local-modelling_:
  - An individual model for each time series.
  - Each time series is modeled independently of the others.
- _Global-modelling_:
  - A single model for all time series.
  - Features created from each series do not overlap with other series. Series are related but modeled separately.
- _Multivariate-modelling_:
  - A single model for all time series.
  - Features created from each series are concatenated at each time step. Try to capture dependencies between the series at the same time point.

## Multi-point-ahead prediction strategies:
- _Recursive:_
	- One model is used for the entire forecast horizon.
	- training: The model is trained to predict one point ahead.
	- prediction: The model iteratively predicts each point, using previous predictions to update the features in the test data.
	- Note 1: There is an option to use a “reduced” version, where features are generated for all test observations at once, and unavailable values are filled with NaN.
	- Note 2: Recursive can also be combined with the MIMO strategy, allowing the model to predict model_horizon points ahead at each step.
- _Direct:_
	- Individual models are trained for each point in the forecast horizon.
	- Note 1: There is an option to use "equal_train_size" option, where all models can be trained on the same X_train set, formed for the last model predicting h point. Only the target variable (y) is updated for each model, reducing the time spent generating new training sets.
	- Note 2: Direct can also be combined with MIMO, where each individual model predicts model_horizon points ahead.
- _MultiOutput (MIMO - Multi-input-multi-output):_
 	- One model is trained and used for the entire forecast horizon at once.
	- Note 1: This strategy can also accommodate exogenous features (for local- or global-modelling strategies).
- _FlatWideMIMO:_.
	- A hybrid of Direct and MIMO. One model is trained, but Direct’s features are deployed across the forecast horizon.
	- Note 1: To use FlatWideMIMO with date-related features, h lags of them must be included (with help of LagTransformer).

## Models:
- _Boosting models_: CatBoost, PyBoost.
- _Neural networks_: [DLinear](https://arxiv.org/abs/2205.13504), [CycleNet](https://arxiv.org/abs/2409.18479), [PatchTST](https://arxiv.org/abs/2211.14730), [TimesNet](https://arxiv.org/abs/2210.02186), [GPT2](https://arxiv.org/abs/2302.11939).

## Preprocessing
- _StandardScalerTransformer_: scales features to have zero mean and unit variance.
- _DifferenceNormalizer_: transforms features by subtracting or dividing by their previous value.
- _TimeToNumGenerator_ and _DateSeasonsGenerator_: generates seasonal features (e.g., month, quarter, day of the week) from date information.
- _LabelEncodingTransformer_ and _OneHotEncodingTransformer_: encodes categorical features.
- _MissingValuesImputer_: handles missing values by imputing them with a chosen strategy.
- _LagTransformer_: generates lagged features.
- _LastKnownNormalizer_: normalizes lagged features by the last known value in history, either by subtracting it or dividing by it.

<a name="citation"></a>
## Citation
If you use Tsururu in your research, please cite it as below. ["Tsururu: a Time Series Forecasting Strategies Framework"](https://arxiv.org/pdf/2509.15843) arXiv:2509.15843

BibTeX entry:
```bibtex
@article{tsururu2025,
  title={Tsururu: A Python-based Time Series Forecasting Strategies Library},
  author={Kostromina, Alina and Kuvshinova, Kseniia and Yugay, Aleksandr and Savchenko, Andrey and Simakov, Dmitry},
  booktitle={Proceedings of the Thirty-Fourth International Joint Conference on Artificial Intelligence},
  year={2025},
  pages={11077-11081},
  doi={10.24963/ijcai.2025/1266}
}
```
<a name="license"></a>
# License
This project is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/sb-ai-lab/tsururu/blob/master/LICENSE) file for more details.

[Back to top](#toc)