### Quick Start Tutorial Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/README.md A simple usage example for getting started with Tsururu. ```python Tutorial_1_Quick_start.ipynb ``` -------------------------------- ### Install Benchmark Dependencies Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/all_configurations_benchmark/alternative_aggregations.ipynb Installs or upgrades necessary packages for running the benchmark. Ensure you have pip, setuptools, and wheel installed. ```python # !pip install --upgrade pip setuptools wheel ``` -------------------------------- ### Create Virtual Environment and Install Dependencies Source: https://github.com/sb-ai-lab/tsururu/blob/main/CONTRIBUTING.md Create a virtual environment using uv and install project dependencies. Use --all-extras to install optional dependencies. ```bash uv venv source .venv/bin/activate # Install dependencies # - For standard development: uv sync # - If you need optional-dependencies (see pyproject.toml): uv sync --all-extras ``` -------------------------------- ### Pipeline Easy Setup Parameters Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Configuration dictionary for easy pipeline setup, specifying target lags, date lags, and normalization methods. Ensure target_normalizer_regime matches the chosen target_normalizer. ```python pipeline_easy_params = { "target_lags": 3, "date_lags": 1, # "exog_lags": 1, # Uncomment this line if you have exogenous features # One from ["none", "standard_scaler", "difference_normalizer", "last_known_normalizer"] "target_normalizer": "standard_scaler", # One from ["none", "delta", "ratio"] (MUST BE "none" for "standard_scaler" and NOT "none" for others) "target_normalizer_regime": "none", } ``` -------------------------------- ### Easy Pipeline Setup Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Instantiates a pipeline using the easy_setup method with provided dataset and pipeline parameters. Ensure dataset_params and pipeline_easy_params are defined. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) ``` -------------------------------- ### Pipeline from Dictionary Setup Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Instantiates a pipeline from a detailed dictionary configuration. Ensure the pipeline_params dictionary is correctly structured. ```python pipeline = Pipeline.from_dict(pipeline_params, multivariate=False) ``` -------------------------------- ### Clone Repository and Install uv Source: https://github.com/sb-ai-lab/tsururu/blob/main/CONTRIBUTING.md Clone your fork of the Tsururu repository and install the uv dependency manager. ```bash git clone https://github.com//tsururu.git cd tsururu python -m pip install uv ``` -------------------------------- ### Install Tsururu from PyPI Source: https://github.com/sb-ai-lab/tsururu/blob/main/README.md Installs the Tsururu library from PyPI. It is recommended to install with at least one set of model dependencies. ```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] ``` -------------------------------- ### Example Script for Benchmarking Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/README.md This script is used for benchmarking available strategies, models, and preprocessing methods on a dataset. ```python Example_1_All_configurations.py ``` -------------------------------- ### Training Output Example Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Example output during the training phase, indicating the progress and data shapes used for training. ```text Output: ------------------------------------Training model for horizon 1------------------------------------ raw_ts_X_for_training: (10000, 16) X for training: (9920, 28) ``` -------------------------------- ### Setup Direct Strategy Pipeline Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Sets up a forecasting pipeline using the Direct Strategy. This strategy trains individual models for each step in the forecast horizon. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) ``` ```python strategy = DirectStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, ) ``` -------------------------------- ### Configure Feature Transformation Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_3_Transformers_and_Pipeline.ipynb Example configuration for enabling feature transformation and setting up a LagTransformer. Ensure 'transform_target' is False when using exogenous features. ```python { "transform_features": True }, "LagTransformer": {"lags": 7}, }, ``` -------------------------------- ### MIMO Strategy Training Setup Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Details the data preparation for training a MIMO forecasting strategy, showing the raw and processed input shapes for the model. ```python ------------------------------------Training model for horizon 3------------------------------------ raw_ts_X_for_training: (10000, 16) X for training: (9910, 28) ``` -------------------------------- ### Quick Tour: Setting up Tsururu for Time Series Forecasting Source: https://github.com/sb-ai-lab/tsururu/blob/main/README.md Demonstrates the basic setup for time series forecasting using Tsururu, including dataset loading, pipeline creation, model training, and prediction. Ensure pandas is imported as pd. ```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) ``` -------------------------------- ### Initialize DLTrainer Parameters Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Defines parameters for the DLTrainer, including device, number of workers, metric-based saving, and scheduler configuration. This setup is crucial for controlling the training process. ```python trainer_params = { "device": "cpu", "num_workers": 0, "best_by_metric": True, "save_to_dir": False, "n_epochs": 1, "scheduler": scheduler, "scheduler_after_epoch": scheduler_after_epoch, "scheduler_params": scheduler_params, "verbose": False, } trainer = DLTrainer( model, model_params, validation, validation_params, **trainer_params ) ``` -------------------------------- ### Install Required Packages Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/all_configurations_benchmark/notebooks/aggregated_results.ipynb Installs necessary packages for critical difference diagrams and Jupyter TikZ extension. Ensure pip, setuptools, and wheel are up-to-date before installing critdd. ```python # For some graphs, the following packages are required: # !pip install --upgrade pip setuptools wheel # !pip install 'critdd @ git+https://github.com/mirkobunse/critdd' # Before installing the jupyter_tikz extension, you need to install some pre-requisites: # https://jupyter-tikz.readthedocs.io/stable/installation/ # !pip install jupyter-tikz ``` -------------------------------- ### Example DataFrame Structure Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Illustrates the structure of the resulting DataFrame after fitting the strategy, including original values, scaled features, and date-based seasonality components. ```python Result: id value date value__standard_scaler date__season_y \ 0 0 1000.0 2020-01-01 -1.729454 2020 1 0 1001.0 2020-01-02 -1.725992 2020 2 0 1002.0 2020-01-03 -1.722530 2020 3 0 1003.0 2020-01-04 -1.719067 2020 4 0 1004.0 2020-01-05 -1.715605 2020 date__season_m date__season_d date__season_doy date__season_wd \ 0 1 3 3 4 1 1 4 4 5 2 1 5 5 6 3 1 6 6 0 4 1 7 7 1 date__season_y__standard_scaler date__season_m__standard_scaler \ 0 -1.145979 -1.550044 1 -1.145979 -1.550044 2 -1.145979 -1.550044 3 -1.145979 -1.550044 4 -1.145979 -1.550044 date__season_d__standard_scaler date__season_doy__standard_scaler \ 0 -1.450887 -1.663056 1 -1.336860 -1.653145 2 -1.222832 -1.643235 3 -1.108804 -1.633324 4 -0.994777 -1.623414 date__season_wd__standard_scaler id__label id__label__standard_scaler 0 0.499725 0 -1.566621 1 0.999450 0 -1.566621 2 1.499176 0 -1.566621 3 -1.499176 0 -1.566621 4 -0.999450 0 -1.566621 ``` -------------------------------- ### Recursive Strategy Setup Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Initializes a recursive strategy for multi-point-ahead forecasting. This strategy iteratively predicts each point, using previous predictions to update features. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) strategy = RecursiveStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, ) ``` -------------------------------- ### Setup RecursiveStrategy with MIMO Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Initializes a forecasting pipeline and configures the RecursiveStrategy for MIMO forecasting. Ensure the overall forecasting horizon is divisible by the model's horizon without a remainder. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) strategy = RecursiveStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, model_horizon=2, ) ``` -------------------------------- ### Setup DirectStrategy with Equal Train Size Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Initialize the DirectStrategy with 'equal_train_size' set to True. This requires a pre-configured pipeline, dataset parameters, and trainer. Use this when you want to train multiple models on the same feature set to reduce computation. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) strategy = DirectStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, equal_train_size=True, ) ``` -------------------------------- ### Exogenous Variable Configuration (Commented Out) Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Example configuration for including exogenous variables in the pipeline. Note that 'transform_target' must be set to False for exogenous features. Support for exogenous variables is currently tested for MIMOStrategy. ```python # pipeline_params["exog_group_1"] = { # "columns": ["value"], # "features": { # "StandardScalerTransformer": # { # "transform_target": False, # "transform_features": True # }, # "LagTransformer": {"lags": 7}, # }, # } ``` -------------------------------- ### MIMO Strategy Output Example Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Displays a sample of the output generated by a MIMO (Multiple-Input Multiple-Output) forecasting strategy. This shows the first few rows and columns of the resulting DataFrame, indicating lagged values of a scaled feature. ```python Result: value__standard_scaler__lag_6 value__standard_scaler__lag_5 \ 0 -1.729454 -1.725992 1 -1.725992 -1.722530 2 -1.722530 -1.719067 3 -1.719067 -1.715605 value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 -1.722530 -1.719067 1 -1.719067 -1.715605 2 -1.715605 -1.712142 3 -1.712142 -1.708680 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 -1.719067 -1.715605 1 -1.715605 -1.712142 2 -1.712142 -1.708680 3 -1.708680 -1.705217 value__standard_scaler__lag_0 0 -1.715605 1 -1.712142 2 -1.708680 3 -1.705217 ``` -------------------------------- ### Configure Model, Validator, and Trainer Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Sets up the CatBoost model with specified parameters, K-Fold cross-validation, and an ML Trainer. ```python model = CatBoost model_params = { "loss_function": "MultiRMSE", "early_stopping_rounds": 100, "verbose": 500, } validation = KFoldCrossValidator validation_params = { "n_splits": 2, } trainer_params = {} trainer = MLTrainer( model, model_params, validation, validation_params, ) ``` -------------------------------- ### Initializing FlatWideMIMOStrategy Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Creates an instance of the FlatWideMIMOStrategy. Requires a pre-configured pipeline, forecast horizon, history length, and a trainer. ```python strategy = FlatWideMIMOStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, ) ``` -------------------------------- ### Get Current Timestamp Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/all_configurations_benchmark/clean_results.ipynb Retrieves the current date and time and formats it as a string for use in filenames or logs. ```python time_now = datetime.now().strftime("%Y-%m-%d") print(f"Time: {time_now}") ``` -------------------------------- ### Configure Trainer Parameters for Finetuning Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Set up trainer parameters including device, worker count, checkpoint saving, pretrained and checkpoint paths, and averaging snapshots for finetuning. ```python trainer_params = { "device": "cpu", "num_workers": 0, "best_by_metric": True, # Let's enable save_to_dir (by the way, default value is True) "save_to_dir": True, "pretrained_path": "checkpoints/", "checkpoint_path": "checkpoints_finetuned/", # Save checkpoints for 3 best model "save_k_best": 3, # Average checkpoints for the final model "average_snapshots": True, "verbose": False, } trainer = DLTrainer( model, model_params, validation, validation_params, **trainer_params ) strategy = MIMOStrategy( pipeline=pipeline, trainer=trainer, horizon=horizon, history=history, ) ``` -------------------------------- ### Forecast Result Example Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Sample of the resulting forecast values after the strategy has been fitted and applied. Displays a DataFrame with scaled feature values. ```text Result: value__standard_scaler__lag_6 value__standard_scaler__lag_5 \ 0 -1.729454 -1.725992 1 -1.725992 -1.722530 2 -1.722530 -1.719067 3 -1.719067 -1.715605 4 -1.715605 -1.712142 value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 -1.722530 -1.719067 1 -1.719067 -1.715605 2 -1.715605 -1.712142 3 -1.712142 -1.708680 4 -1.708680 -1.705218 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 -1.715605 -1.712142 1 -1.712142 -1.708680 2 -1.708680 -1.705218 3 -1.705218 -1.701755 4 -1.701755 -1.698293 value__standard_scaler__lag_0 id__label__standard_scaler__lag_0 \ 0 -1.708680 -1.566621 1 -1.705218 -1.566621 2 -1.701755 -1.566621 3 -1.698293 -1.566621 4 -1.694831 -1.566621 date__season_y__standard_scaler__lag_3 \ 0 -1.145979 1 -1.145979 2 -1.145979 3 -1.145979 4 -1.145979 date__season_y__standard_scaler__lag_2 ... \ 0 -1.145979 ... 1 -1.145979 ... 2 -1.145979 ... 3 -1.145979 ... 4 -1.145979 ... date__season_d__standard_scaler__lag_1 \ 0 -0.880749 1 -0.766722 2 -0.652694 3 -0.538666 4 -0.424639 date__season_d__standard_scaler__lag_0 \ 0 -0.766722 1 -0.652694 2 -0.538666 3 -0.424639 4 -0.310611 date__season_doy__standard_scaler__lag_3 \ 0 -1.633324 1 -1.623414 2 -1.613504 3 -1.603593 4 -1.593683 date__season_doy__standard_scaler__lag_2 \ 0 -1.623414 1 -1.613504 2 -1.603593 3 -1.593683 4 -1.583772 date__season_doy__standard_scaler__lag_1 \ 0 -1.613504 1 -1.603593 2 -1.593683 3 -1.583772 4 -1.573862 date__season_doy__standard_scaler__lag_0 \ 0 -1.603593 1 -1.593683 2 -1.583772 3 -1.573862 4 -1.563952 date__season_wd__standard_scaler__lag_3 \ 0 -1.499176 1 -0.999450 2 -0.499725 3 0.000000 4 0.499725 date__season_wd__standard_scaler__lag_2 \ 0 -0.999450 1 -0.499725 2 0.000000 ``` -------------------------------- ### Transformers and Pipeline Tutorial Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/README.md This tutorial provides a description of available data preprocessing techniques using transformers and pipelines. ```python Tutorial_3_Transformers_and_Pipeline.ipynb ``` -------------------------------- ### Neural Networks Tutorial Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/README.md This tutorial demonstrates working with neural networks in Tsururu. ```python Tutorial_4_Neural_Networks.ipynb ``` -------------------------------- ### Forecasting Strategies Tutorial Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/README.md This tutorial covers various forecasting strategies available in Tsururu. ```python Tutorial_2_Strategies.ipynb ``` -------------------------------- ### Setting up MIMO Strategy Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Initializes a multi-input multi-output (MIMO) strategy for time series forecasting. Requires dataset parameters, pipeline parameters, and trainer configuration. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=True) strategy = MIMOStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, ) ``` -------------------------------- ### Plot Critical Difference Diagram Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/all_configurations_benchmark/notebooks/aggregated_results.ipynb Generates a critical difference diagram to visualize the performance comparison between different preprocessing methods. Requires TikZ and preamble setup. ```python %tikz "$critical_difference_code" -p "$preamble" -r -d=200 ``` -------------------------------- ### Training Data Preparation for Recursive Forecasting Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Shows the shape of the target variable (y) prepared for training in a recursive forecasting setup. This is typically a single time series column. ```python y for training: (9930, 1) [[-1.70521765] [-1.70175528] [-1.69829291] [-1.69483054] [-1.69136817]] ``` -------------------------------- ### Feature Engineering Example Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Illustrates the creation of lag features for a time series, specifically showing the 'Day' frequency and a period of 1. This is a common step in time series preprocessing. ```python freq: Day; period: 1 raw_ts_X on step: 0 (11,) ``` -------------------------------- ### Training Data Sample Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb This displays a sample of the prepared training data, including original values and scaled features, along with date and ID information. ```python Result: id value date value__standard_scaler date__season_y \ 3000 3 4000.0 2020-01-01 -1.729454 2020 3001 3 4001.0 2020-01-02 -1.725992 2020 3002 3 4002.0 2020-01-03 -1.722530 2020 3003 3 4003.0 2020-01-04 -1.719067 2020 3004 3 4004.0 2020-01-05 -1.715605 2020 date__season_m date__season_d date__season_doy date__season_wd \ 3000 1 5 5 6 3001 1 6 6 0 3002 1 7 7 1 3003 1 8 8 2 3004 1 9 9 3 date__season_y__standard_scaler date__season_m__standard_scaler \ 3000 -1.149847 -1.556765 3001 -1.149847 -1.556765 3002 -1.149847 -1.556765 3003 -1.149847 -1.556765 3004 -1.149847 -1.556765 date__season_d__standard_scaler date__season_doy__standard_scaler \ 3000 -1.227586 -1.650713 3001 -1.113667 -1.640789 3002 -0.999749 -1.630866 3003 -0.885830 -1.620943 3004 -0.771912 -1.611019 date__season_wd__standard_scaler id__label id__label__standard_scaler 3000 1.500250 0 NaN 3001 -1.498251 0 NaN 3002 -0.998501 0 NaN 3003 -0.498751 0 NaN 3004 0.001000 0 NaN ``` -------------------------------- ### Configure MLTrainer with CatBoost and KFoldCrossValidator Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Sets up an MLTrainer instance using CatBoost for modeling and KFoldCrossValidator for validation. Ensure CatBoost and KFoldCrossValidator are imported before use. ```python model = CatBoost model_params = { "loss_function": "MultiRMSE", "early_stopping_rounds": 100, "verbose": 500, } validation = KFoldCrossValidator validation_params = { "n_splits": 2, } trainer_params = {} trainer = MLTrainer( model, model_params, validation, validation_params, ) ``` -------------------------------- ### MIMO Strategy Feature Engineering Example Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Illustrates the feature engineering process for a MIMO strategy, focusing on scaled lagged values of the 'value' column. This prepares the input features for the model. ```python Result: value__standard_scaler__lag_6 value__standard_scaler__lag_5 \ 0 1.70868 1.712142 1 1.70868 1.712142 2 1.70868 1.712142 3 1.70868 1.712142 4 1.70868 1.712142 value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 1.715605 1.719067 1 1.715605 1.719067 2 1.715605 1.719067 3 1.715605 1.719067 4 1.715605 1.719067 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 1.72253 1.725992 1 1.72253 1.725992 2 1.72253 1.725992 3 1.72253 1.725992 4 1.72253 1.725992 ``` -------------------------------- ### Configure Trainer Parameters Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Sets up parameters for the DLTrainer, including device, workers, epochs, pre-trained model path, and checkpoint averaging. ```python trainer_params = { "device": "cpu", "num_workers": 0, "n_epochs": 1, "pretrained_path": "checkpoints_finetuned/", # Average checkpoints for the final model "average_snapshots": True, "verbose": False, } trainer = DLTrainer( model, model_params, validation, validation_params, **trainer_params ) strategy = MIMOStrategy( pipeline=pipeline, trainer=trainer, horizon=horizon, history=history, ) ``` -------------------------------- ### Example DataFrame Structure with Lags Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Presents the structure of the DataFrame containing lagged features, which are crucial for time series forecasting models. This includes lagged values of the target variable and other features. ```python Result: value__standard_scaler__lag_6 value__standard_scaler__lag_5 \ 0 -1.729454 -1.725992 1 -1.725992 -1.722530 2 -1.722530 -1.719067 3 -1.719067 -1.715605 4 -1.715605 -1.712142 value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 -1.722530 -1.719067 1 -1.719067 -1.715605 2 -1.715605 -1.712142 3 -1.712142 -1.708680 4 -1.708680 -1.705218 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 -1.715605 -1.712142 1 -1.712142 -1.708680 2 -1.708680 -1.705218 3 -1.705218 -1.701755 4 -1.701755 -1.698293 value__standard_scaler__lag_0 id__label__standard_scaler__lag_0 \ 0 -1.708680 -1.566621 1 -1.705218 -1.566621 2 -1.701755 -1.566621 3 -1.698293 -1.566621 4 -1.694831 -1.566621 date__season_y__standard_scaler__lag_3 \ 0 -1.145979 1 -1.145979 2 -1.145979 3 -1.145979 4 -1.145979 date__season_y__standard_scaler__lag_2 ... \ 0 -1.145979 ... 1 -1.145979 ... 2 -1.145979 ... 3 -1.145979 ... 4 -1.145979 ... ``` -------------------------------- ### Helper function to get results Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb A utility function to format and retrieve forecasting results, organizing true values, predictions, and IDs into a pandas DataFrame across multiple cross-validation folds. ```python def get_results( cv: int, regime: str, y_true: Optional[List[np.ndarray]] = None, y_pred: Optional[List[np.ndarray]] = None, ids: Optional[List[Union[float, str]]] = None, ) -> pd.DataFrame: def _get_fold_value( value: Optional[Union[float, np.ndarray]], idx: int ) -> List[Optional[Union[float, np.ndarray]]]: if value is None: return [None] if isinstance(value[idx], float): return value[idx] if isinstance(value[idx], np.ndarray): return value[idx].reshape(-1) raise TypeError(f"Unexpected value type. Value: {value}") df_res_dict = {} for idx_fold in range(cv): # Fill df_res_dict for name, value in [("y_true", y_true), ("y_pred", y_pred)]: df_res_dict[f"{name}_{idx_fold + 1}"] = _get_fold_value(value, idx_fold) if regime != "local": df_res_dict[f"id_{idx_fold + 1}"] = _get_fold_value(ids, idx_fold) # Save datasets to specified directory df_res = pd.DataFrame(df_res_dict) return df_res ``` -------------------------------- ### Iterating Through Time Series IDs for Local Modeling Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb This loop simulates local modeling by iterating through each unique time series ID in the dataset. It prints a header for each ID to indicate the start of training for that series. ```python preds_list = [] for ts_id in dataset.data["id"].unique(): print(f"Training for ts_id: {ts_id}".center(100, "-"), "\n") ``` -------------------------------- ### Define Benchmark Configuration Parameters Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/all_configurations_benchmark/clean_results.ipynb Defines lists of models, datasets, strategies, and various configuration parameters used in the benchmark experiments. ```python MODELS = [ "PyBoost", "DLinear_NN", "PatchTST_NN", "GPT4TS_NN", "TimesNet_NN", "TimeMixer_NN", "CycleNet_NN", ] DATASETS = ["ILI"] STRATEGY_TIMES = [ "FlatWideMIMOStrategy__model_horizon_NaN", "MIMOStrategy__model_horizon_NaN", "RecursiveStrategy__model_horizon_1.0", "RecursiveStrategy__model_horizon_6.0", ] DATETIMES = ["False", "with_normalization_over_all"] IDS = ["False", "with_le_normalization_over_all"] TRANSFORMER_NAMES = [ "NaN", "DifferenceNormalizer", "LastKnownNormalizer", ] TRANSFORMER_REGIMES = ["NaN", "delta"] TRANSFORMER_TR_FEATURES = ["True"] TRANSFORMER_TR_TARGETS = ["True"] REGIMES = ["multivariate", "global"] CI = ["False", "True"] ``` -------------------------------- ### Setting up Easy Pipeline for Reduced Strategy Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Initializes a pipeline for a reduced strategy, where features are generated for all test observations at once. Unavailable values are filled with NaN. ```python pipeline = Pipeline.easy_setup(dataset_params, pipeline_easy_params, multivariate=False) strategy = RecursiveStrategy( horizon=horizon, history=history, pipeline=pipeline, trainer=trainer, reduced=True, ) ``` -------------------------------- ### Training Data Preparation for Specific Time Series Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Indicates the start of training for a specific time series ID (e.g., 6). It shows the frequency and period for the data, and the shape of the training features (X) for that series. ```python ---------------------------------------Training for ts_id: 6---------------------------------------- freq: Day; period: 1 raw_ts_X_for_training: (1000, 16) ``` -------------------------------- ### Sample Test Data Output Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb This displays a sample of the prepared test data, showing the first row and its features after preprocessing. ```python Result: value__standard_scaler__lag_6 value__standard_scaler__lag_5 \ 0 1.70868 1.712142 value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 1.715605 1.719067 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 1.72253 1.725992 value__standard_scaler__lag_0 id__label__standard_scaler__lag_0 \ 0 1.729454 NaN date__season_y__standard_scaler__lag_3 \ 0 1.374515 date__season_y__standard_scaler__lag_2 ... \ 0 1.374515 ... date__season_d__standard_scaler__lag_1 \ 0 1.506458 date__season_d__standard_scaler__lag_0 \ 0 1.620377 date__season_doy__standard_scaler__lag_3 \ 0 0.978964 date__season_doy__standard_scaler__lag_2 \ 0 0.988887 date__season_doy__standard_scaler__lag_1 \ 0 0.998811 date__season_doy__standard_scaler__lag_0 \ 0 1.008734 date__season_wd__standard_scaler__lag_3 \ 0 -0.998501 date__season_wd__standard_scaler__lag_2 \ 0 -0.498751 date__season_wd__standard_scaler__lag_1 \ 0 0.001 date__season_wd__standard_scaler__lag_0 0 0.50075 [1 rows x 28 columns] ``` -------------------------------- ### Data Preview for Training Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Displays the initial state of the data, including lagged values and seasonal features, before training. ```python value__standard_scaler__lag_4 value__standard_scaler__lag_3 \ 0 1.715605 1.719067 value__standard_scaler__lag_2 value__standard_scaler__lag_1 \ 0 1.72253 1.725992 value__standard_scaler__lag_0 id__label__standard_scaler__lag_0 \ 0 1.729454 NaN date__season_y__standard_scaler__lag_3 \ 0 1.374515 date__season_y__standard_scaler__lag_2 ... \ 0 1.374515 ... date__season_d__standard_scaler__lag_1 \ 0 1.506458 date__season_d__standard_scaler__lag_0 \ 0 1.620377 date__season_doy__standard_scaler__lag_3 \ 0 0.978964 date__season_doy__standard_scaler__lag_2 \ 0 0.988887 date__season_doy__standard_scaler__lag_1 \ 0 0.998811 date__season_doy__standard_scaler__lag_0 \ 0 1.008734 date__season_wd__standard_scaler__lag_3 \ 0 -0.998501 date__season_wd__standard_scaler__lag_2 \ 0 -0.498751 date__season_wd__standard_scaler__lag_1 \ 0 0.001 date__season_wd__standard_scaler__lag_0 0 0.50075 [1 rows x 28 columns] ``` -------------------------------- ### Configure Trainer Parameters for Checkpointing Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Set up trainer parameters to enable checkpointing, specify save directories, and control the number of best models to save. This configuration is essential for resuming training or selecting the best performing model. ```python trainer_params = { "device": "cpu", "num_workers": 0, "best_by_metric": True, # Let's enable save_to_dir (by the way, default value is True) "save_to_dir": True, "checkpoint_path": "checkpoints/", # Save checkpoints for 3 best model "save_k_best": 3, # Average checkpoints for the final model "average_snapshots": True, "verbose": False, } trainer = DLTrainer( model, model_params, validation, validation_params, **trainer_params ) strategy = MIMOStrategy( pipeline=pipeline, trainer=trainer, horizon=horizon, history=history, ) ``` -------------------------------- ### Training Initialization for Time Series ID 5 Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_2_Strategies.ipynb Indicates the start of the training process for a specific time series ID (5). It also confirms the frequency and period of the data, along with the shape of the input features for training. ```python Output: ---------------------------------------Training for ts_id: 5---------------------------------------- freq: Day; period: 1 raw_ts_X_for_training: (1000, 16) ``` -------------------------------- ### Initialize MIMOStrategy Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Creates an instance of MIMOStrategy, which combines a pipeline, a trained model, and forecasting parameters. This strategy is used for multi-input multi-output forecasting. ```python strategy = MIMOStrategy( pipeline=pipeline, trainer=trainer, horizon=horizon, history=history, ) ``` -------------------------------- ### Training Output Log Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_4_Neural_Networks.ipynb Example log output showing the progress of neural network training, including epoch number, training loss, validation loss, and metric scores. This output is typical during the model fitting process. ```text Output: length of train dataset: 4935 length of val dataset: 4935 ``` ```text Output: Epoch 1/10, cost time: 2.65s train loss: 4887171.9910 Validation, Loss: 1047792.3750, Metric: -1047792.3750 val loss: 1047792.3750, val metric: -1047792.3750 Epoch 2/10, cost time: 2.48s train loss: 706722.3347 Validation, Loss: 462100.9062, Metric: -462100.9062 val loss: 462100.9062, val metric: -462100.9062 Epoch 3/10, cost time: 2.46s train loss: 276882.1953 Validation, Loss: 154248.0312, Metric: -154248.0312 val loss: 154248.0312, val metric: -154248.0312 Epoch 4/10, cost time: 2.48s train loss: 83515.5311 Validation, Loss: 39639.5547, Metric: -39639.5547 val loss: 39639.5547, val metric: -39639.5547 Epoch 5/10, cost time: 2.45s train loss: 19590.2556 Validation, Loss: 8090.8174, Metric: -8090.8174 val loss: 8090.8174, val metric: -8090.8174 Epoch 6/10, cost time: 3.00s train loss: 3694.6669 Validation, Loss: 1400.1285, Metric: -1400.1285 val loss: 1400.1285, val metric: -1400.1285 Epoch 7/10, cost time: 3.29s train loss: 635.7974 Validation, Loss: 266.9762, Metric: -266.9762 val loss: 266.9762, val metric: -266.9762 Epoch 8/10, cost time: 2.93s train loss: 150.1327 Validation, Loss: 89.3946, Metric: -89.3946 val loss: 89.3946, val metric: -89.3946 Epoch 9/10, cost time: 2.74s train loss: 62.6007 Validation, Loss: 44.3605, Metric: -44.3605 val loss: 44.3605, val metric: -44.3605 Epoch 10/10, cost time: 2.84s train loss: 32.5973 Validation, Loss: 23.0942, Metric: -23.0942 val loss: 23.0942, val metric: -23.0942 Fold 0. Score: -23.094181060791016 length of train dataset: 4935 length of val dataset: 4935 Epoch 1/10, cost time: 2.82s train loss: 4629491.8015 Validation, Loss: 983696.3750, Metric: -983696.3750 val loss: 983696.3750, val metric: -983696.3750 Epoch 2/10, cost time: 2.53s train loss: 698127.7240 Validation, Loss: 403440.4688, Metric: -403440.4688 val loss: 403440.4688, val metric: -403440.4688 Epoch 3/10, cost time: 2.52s train loss: 250679.8958 Validation, Loss: 121161.9219, Metric: -121161.9219 val loss: 121161.9219, val metric: -121161.9219 Epoch 4/10, cost time: 2.52s train loss: 67178.7610 Validation, Loss: 27191.2715, Metric: -27191.2715 val loss: 27191.2715, val metric: -27191.2715 Epoch 5/10, cost time: 2.53s train loss: 13710.6542 Validation, Loss: 4644.9053, Metric: -4644.9053 val loss: 4644.9053, val metric: -4644.9053 Epoch 6/10, cost time: 2.51s train loss: 2181.1388 Validation, Loss: 668.1273, Metric: -668.1273 val loss: 668.1273, val metric: -668.1273 Epoch 7/10, cost time: 2.53s train loss: 317.9138 Validation, Loss: 117.8485, Metric: -117.8485 val loss: 117.8485, val metric: -117.8485 Epoch 8/10, cost time: 2.54s train loss: 73.0912 Validation, Loss: 43.1988, Metric: -43.1988 val loss: 43.1988, val metric: -43.1988 Epoch 9/10, cost time: 2.50s train loss: 31.8865 Validation, Loss: 22.1970, Metric: -22.1970 val loss: 22.1970, val metric: -22.1970 Epoch 10/10, cost time: 2.51s train loss: 16.3420 Validation, Loss: 11.1961, Metric: -11.1961 val loss: 11.1961, val metric: -11.1961 Fold 1. Score: -11.196077346801758 Mean score: -17.1451 Std: 5.9491 ``` -------------------------------- ### Run Pre-commit Hooks Source: https://github.com/sb-ai-lab/tsururu/blob/main/CONTRIBUTING.md Manually run pre-commit hooks to verify all files before committing changes. ```bash uv run pre-commit run --all-files ``` -------------------------------- ### Initialize Recursive Forecasting Strategy Source: https://github.com/sb-ai-lab/tsururu/blob/main/examples/Tutorial_1_Quick_start.ipynb Initializes a Recursive forecasting strategy using the configured trainer and pipeline. ```python strategy = RecursiveStrategy(horizon, history, trainer, pipeline) ```