DOCSEARCHbyAlgolia
Submit Docs

Tsururu: Python Tool for Time Series Forecasting

repository·main·Indexed 42 days ago

https://github.com/sb-ai-lab/tsururu

Tsururu version 1.1.0 is a Python-based framework for time series forecasting strategies, focusing on training and inference methodologies. It supports multi-series (local, global, and multivariate modeling) and multi-point-ahead prediction strategies including Recursive, Direct, MultiOutput (MIMO), and FlatWideMIMO. The framework integrates boosting models like CatBoost and PyBoost, as well as neural networks such as DLinear, CycleNet, PatchTST, TimesNet, and GPT2, alongside a comprehensive suite of preprocessing transformers.

Tokens
12K
Snippets
31
Records
40
Agent score
53%

What's inside Tsururu

  1. Understand multi-series prediction strategies

    main

    Tsururu categorizes multi-series modeling into three approaches:

    • Local-modelling: An individual model is trained for each time series independently.
    • Global-modelling: A single model is trained for all time series. Features created from each series do not overlap with other series.
    • Multivariate-modelling: A single model is trained for all time series, but features from each series are concatenated at each time step to capture dependencies between series at the same time point.

  2. Understand multi-point-ahead prediction strategies

    main

    Tsururu provides several strategies for predicting multiple points into the future:

    • Recursive: Uses one model for the entire horizon. It predicts one point ahead and iteratively uses that prediction to update features for the next step. Can be combined with MIMO.
    • Direct: Trains individual models for each specific point in the forecast horizon. Supports an equal_train_size option to speed up training by using the same X_train set for all models.
    • MultiOutput (MIMO - Multi-input-multi-output): A single model is trained to predict the entire forecast horizon at once. Can accommodate exogenous features.
    • FlatWideMIMO: A hybrid of Direct and MIMO. One model is trained, but Direct-style features are deployed across the forecast horizon. Requires LagTransformer for date-related features.

  3. Reproduce original model implementations

    main

    The reproducibility_check directory contains scripts designed to reproduce the results of original model implementations and compare them against Tsururu's versions.

    To execute the full reproducibility pipeline end-to-end, run the provided shell script. You can also launch specific experiments using a configuration file.

    # Execute the full reproducibility pipeline
./run_all.sh

# Or launch specific experiments
python run_exp.py

  4. Quick start guide for Tsururu

    main

    To perform time series forecasting, you typically follow these steps:

    1. Define dataset_params specifying the target, date, and id columns.
    2. Initialize a TSDataset with your data.
    3. Create a Pipeline using Pipeline.easy_setup to handle preprocessing (e.g., lags).
    4. Initialize an MLTrainer with a model (e.g., CatBoost) and a validator (e.g., KFoldCrossValidator).
    5. Define a Strategy (e.g., RecursiveStrategy) with your desired horizon and history.
    6. Call .fit(dataset) to train and .predict(dataset) to generate forecasts.
    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
import pandas as pd

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)

  5. Install Tsururu via pip

    main

    You can install the base functionality of Tsururu from PyPI. However, it is highly recommended to install additional dependencies for specific models. You can perform a partial installation using specific extras or install everything using the all option.

    Extra dependency options:

    • catboost
    • torch
    • pyboost
    • all (installs all dependencies)
    # Base functionality
pip install -U tsururu

# Partial installation with catboost
pip install -U tsururu[catboost]

# Install all dependencies
pip install -U tsururu[all]

  6. Explore Tsururu Tutorials and Examples

    main

    Tsururu provides several tutorials and example scripts to help you understand different aspects of the framework, including forecasting strategies, neural networks, and data preprocessing.

    Key resources available in the examples/ directory:

    • Tutorial_1_Quick_start.ipynb: Simple usage examples for getting started.
    • Tutorial_2_Strategies.ipynb: Detailed coverage of forecasting strategies.
    • Tutorial_3_Transformers_and_Pipeline.ipynb: Description of available data preprocessing techniques.
    • Tutorial_4_Neural_Networks.ipynb: Demonstrations of working with neural networks.
    • Example_1_All_configurations.py: A script for benchmarking available strategies, models, and preprocessing methods on a dataset.

  7. Benchmark models and strategies on custom datasets

    main

    To run experiments and benchmark different models and strategies on your own datasets or new models, follow this workflow using the tools in the all_configurations_benchmark directory:

    1. Configure Settings: Add your new dataset and model settings to scripts/constants.py.
    2. Launch Experiments: Run scripts/run_exp.py to start the benchmarking process.
      • Note: Use scripts/run_exp_ratio.py if you are working with the ratio regime in transformers.
    3. Parse Results: Run scripts/get_results.py to parse the raw logs and generate a CSV file containing scaled metrics.
    4. Clean Data: Use notebooks/clean_results.ipynb to clean and normalize the results produced by get_results.py.
    5. Visualize: Use notebooks/aggregated_results.ipynb to generate summary tables and plots from the cleaned data.
    # Example workflow steps
python scripts/run_exp.py
python scripts/get_results.py
# Then use notebooks to clean and aggregate

  8. How Pipeline and Transformers work together

    main

    A Pipeline manages a sequence of Transformer objects to preprocess data and generate features. Transformers are categorized by their input/output types:

    • Series2Series: Transforms values within a series (e.g., StandardScalerTransformer, DifferenceNormalizer, MissingValuesImputer, DateSeasonsGenerator).
    • Series2Features: Generates features from series values (e.g., LagTransformer, TargetGenerator).
    • Features2Features: Transforms existing features (e.g., LastKnownNormalizer).

    Critical Ordering Rule: Transformers must be assembled in a specific order to function correctly:

    1. SeriesToSeries transformers (e.g., StandardScalerTransformer, DifferenceNormalizer) must come first.
    2. SeriesToFeatures transformers (e.g., LagTransformer, TargetGenerator) must follow.
    3. FeaturesToFeatures transformers (e.g., LastKnownNormalizer) must come last.

    Failure to place LagTransformer in the sequence will result in no features being generated.

  9. Understand the three types of Transformers in tsururu

    main

    Transformers in tsururu are categorized based on when and how they manipulate data during the feature generation process:

    1. Series2Series: These work with the original "long" time series. During training, they add new columns to this series (e.g., normalized values or date-related features).
    2. Series2Features: These convert the transformed long series into the specific feature matrix (X) and target array (y) required by the base model (e.g., generating lags).
    3. Features2Features: These operate directly on the generated feature matrix, modifying existing features (e.g., normalizing lags based on the last known value).

  10. Compose transformations with SequentialTransformer and UnionTransformer

    main

    Use these transformers to build complex transformation logic:

    • SequentialTransformer: Applies a list of transformers in order. Each transformer receives the output of the previous one. Useful for chaining (e.g., StandardScaler $\rightarrow$ LagTransformer).
    • UnionTransformer: Applies several transformers in parallel and combines their results into a single feature matrix. Useful for combining different feature types (e.g., DateSeasonsGenerator + OneHotEncodingTransformer).

  11. Choose a Forecasting Strategy

    main

    A Strategy combines a Trainer and a Pipeline to execute forecasting. Common strategies include:

    • RecursiveStrategy: Trains on one-step-ahead prediction; iteratively uses predictions to shape future features.
    • Recursive-reduced: Similar to Recursive, but generates features for all test observations at once, replacing unavailable values with NaN.
    • Direct: Uses individual models for each point in the prediction horizon.
    • MultiOutput (MIMO): A single model learns to predict the entire horizon at once. This strategy supports exogenous features.
    • FlatWideMIMO: A mixture of Direct and MIMO; fits one model but uses Direct-style features deployed over the horizon. Requires the number of lags for datetime features to equal the horizon.

  12. Configure Schedulers with relative parameters

    main

    Since users don't have direct access to the dataset length inside the trainer, Tsururu provides relative parameters in scheduler_params to automatically scale scheduler settings based on the dataset size and batch size.

    • relative_steps_per_epoch: A multiplier for iterations in one epoch. Used for parameters like steps_per_epoch in OneCycleLR.
      • $absolute_steps_per_epoch = relative_steps_per_epoch \times (len(dataset) // batch_size + 1)$
    • relative_steps: A multiplier of the total number of iterations across all epochs. Used for parameters like T_max in CosineAnnealingLR.
      • $absolute_steps = relative_steps \times n_epochs \times (len(dataset) // batch_size + 1)$

    Example: OneCycleLR

    scheduler = torch.optim.lr_scheduler.OneCycleLR
scheduler_after_epoch = False
scheduler_params = {
    "relative_steps_per_epoch": ["steps_per_epoch"],
    "steps_per_epoch": 1.0,
    "epochs": 10,
    "max_lr": 0.01,
}

    Example: CosineAnnealingLR

    scheduler = torch.optim.lr_scheduler.CosineAnnealingLR
scheduler_after_epoch = False
scheduler_params = {
    "relative_steps": ["T_max"],
    "T_max": 1.0,
}