### Example CHANGELOG entry

Source: https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md

An example of how to format an entry in the CHANGELOG.md file for new contributions, including issue and author links.

```markdown
- Added new feature XYZ. [#001](https://https://github.com/unit8co/darts/pull/001)
  by [<Your Name>](https://github.com/<your-handle>).
```

--------------------------------

### Install Darts and Optuna

Source: https://github.com/unit8co/darts/blob/master/examples/17-hyperparameter-optimization.ipynb

Installs the necessary Darts and Optuna libraries for hyperparameter optimization.

```python
# necessary packages:
!pip install -U darts
!pip install -U optuna
```

--------------------------------

### Setup Python Path

Source: https://github.com/unit8co/darts/blob/master/examples/03-FFT-examples.ipynb

Ensures the correct Python path is set for local development.

```python
# fix python path if working locally
from utils import fix_pythonpath_if_working_locally

fix_pythonpath_if_working_locally()
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md

Sets up automatic code formatting and linting by installing pre-commit hooks. This ensures code style consistency before committing.

```bash
uv run pre-commit install
```

--------------------------------

### Install NeuralForecast Package

Source: https://github.com/unit8co/darts/blob/master/examples/26-NeuralForecast-examples.ipynb

Install the neuralforecast package from PyPI. This is required for using NeuralForecast models within Darts.

```bash
pip install "neuralforecast>=3.0.0"
```

--------------------------------

### Install development dependencies with uv

Source: https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md

Installs all development dependencies for the project using uv. This command ensures all necessary tools for development are available.

```bash
uv sync --group dev-all --upgrade
```

--------------------------------

### Build documentation locally

Source: https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md

Commands to build the project's documentation locally. Ensure pandoc is installed before running these commands.

```bash
# ensure pandoc is available. If not, install it: https://pandoc.org/installing.html
pandoc --version
# build the docs (uv sync already installed darts in editable mode)
uv run make --directory=./docs build-all-docs
```

--------------------------------

### Darts Setup and Imports

Source: https://github.com/unit8co/darts/blob/master/examples/19-EnsembleModel-examples.ipynb

Sets up the Darts environment, including plotting styles, imports necessary modules, and configures warnings and logging.

```python
%load_ext autoreload
%autoreload 2
%matplotlib inline
import warnings

import matplotlib.pyplot as plt

# use darts plotting style
from darts import set_option

set_option("plotting.use_darts_style", True)

from darts.dataprocessing.transformers import Scaler
from darts.datasets import AirPassengersDataset
from darts.metrics import mape
from darts.models import (
    ExponentialSmoothing,
    KalmanForecaster,
    LinearRegressionModel,
    NaiveDrift,
    NaiveEnsembleModel,
    NaiveSeasonal,
    RandomForestModel,
    RegressionEnsembleModel,
    TCNModel,
)
from darts.utils.timeseries_generation import (
    datetime_attribute_timeseries as dt_attr,
)

warnings.filterwarnings("ignore")

import logging

logging.disable(logging.CRITICAL)
```

--------------------------------

### Install uv for dependency management

Source: https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md

Installs the uv package manager, which is used for managing project dependencies and running commands.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Migrate Darts PyPI Installation (Options)

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Updates PyPI installation command for Darts version 0.41.0 and above, for users who previously installed u8darts with specific options.

```bash
pip install "darts[option]>=0.41.0"  # or appropriate extras (e.g. darts[all])
```

--------------------------------

### Install Darts and Dependencies

Source: https://github.com/unit8co/darts/blob/master/examples/14-transfer-learning.ipynb

Installs the 'xlrd' and 'darts' Python packages. Run this cell once to set up the environment.

```bash
%%bash
pip install xlrd
pip install darts
```

--------------------------------

### Install Darts Core from PyPI

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs the core Darts library without optional dependencies like neural networks or gradient boosting models.

```bash
pip install darts
```

--------------------------------

### Setup Python Path and Autoreload

Source: https://github.com/unit8co/darts/blob/master/examples/02-data-processing.ipynb

Ensures the correct Python path for local development and enables automatic reloading of modules.

```python
# fix python path if working locally
from utils import fix_pythonpath_if_working_locally

fix_pythonpath_if_working_locally()

%load_ext autoreload
%autoreload 2
%matplotlib inline
```

--------------------------------

### Model Configuration Parameters

Source: https://github.com/unit8co/darts/blob/master/examples/21-TSMixer-examples.ipynb

Sets up input and output chunk lengths for a probabilistic model prediction. `full_training` is set to `False` for simplicity in this example.

```python
input_chunk_length = 7 * 24
output_chunk_length = 24
use_static_covariates = True
full_training = False
```

--------------------------------

### Import Darts and Plotting Utilities

Source: https://github.com/unit8co/darts/blob/master/examples/10-Kalman-filter-examples.ipynb

Imports necessary libraries and sets up Darts plotting style for use in the examples.

```python
%reload_ext autoreload
%autoreload 2
%matplotlib inline

import matplotlib.pyplot as plt
import numpy as np

# use darts plotting style
from darts import set_option

set_option("plotting.use_darts_style", True)

from darts import TimeSeries
from darts.models import KalmanFilter
from darts.utils import timeseries_generation as tg
```

--------------------------------

### Setup Python Path and Matplotlib

Source: https://github.com/unit8co/darts/blob/master/examples/09-DeepTCN-examples.ipynb

Ensures the correct Python path is set for local development and enables inline plotting with Matplotlib.

```python
from utils import fix_pythonpath_if_working_locally

fix_pythonpath_if_working_locally()
%matplotlib inline
```

--------------------------------

### Train and Predict with Boosted Tree Models

Source: https://github.com/unit8co/darts/blob/master/examples/20-SKLearnModel-examples.ipynb

Initializes LightGBM, XGBoost, and CatBoost models, fits them to training data, makes predictions, and prints the Mean Absolute Percentage Error (MAPE) for each model. Ensure LightGBM, CatBoost, and XGBoost dependencies are installed.

```python
lgbm_model = LightGBMModel(lags=24, output_chunk_length=24, verbose=0)
xgboost_model = XGBModel(lags=24, output_chunk_length=24)
catboost_model = CatBoostModel(lags=24, output_chunk_length=24)

lgbm_model.fit(ts_energy_train)
xgboost_model.fit(ts_energy_train)
catboost_model.fit(ts_energy_train)

pred_lgbm = lgbm_model.predict(n=24)
pred_xgboost = xgboost_model.predict(n=24)
pred_catboost = catboost_model.predict(n=24)

print(f"LightGBMModel MAPE: {mape(ts_energy_val, pred_lgbm)}")
print(f"XGBoostModel MAPE: {mape(ts_energy_val, pred_xgboost)}")
print(f"CatboostModel MAPE: {mape(ts_energy_val, pred_catboost)}")

ts_energy_train[-48:].plot(label="training")
ts_energy_val[:24].plot(label="validation")
pred_lgbm.plot(label="lgbm")
pred_xgboost.plot(label="xgboost")
pred_catboost.plot(label="catboost")
```

--------------------------------

### Install Darts with PyTorch from PyPI

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs the core Darts library along with PyTorch, enabling the use of neural network models.

```bash
pip install "darts[torch]"
```

--------------------------------

### Install All Darts Models from PyPI

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs the core Darts library with all available model dependencies, excluding those explicitly listed as not included.

```bash
pip install "darts[all]"
```

--------------------------------

### Import Darts and Setup Plotting

Source: https://github.com/unit8co/darts/blob/master/examples/24-SKLearnClassifierModel-examples.ipynb

Imports necessary Darts modules and configures plotting style.

```python
%load_ext autoreload
%autoreload 2
%matplotlib inline

import numpy as np
import pandas as pd

# use darts plotting style
from darts import set_option

set_option("plotting.use_darts_style", True)

import darts.utils.timeseries_generation as tg
from darts import TimeSeries, metrics
from darts.models import CatBoostClassifierModel
```

--------------------------------

### Conformalized Quantile Regression

Source: https://github.com/unit8co/darts/blob/master/examples/23-Conformal-Prediction-examples.ipynb

Demonstrates the usage of ConformalQRModel, which requires a probabilistic base forecaster. This example performs a single-step forecast and shows backtesting results, comparing coverage and interval width against the naive conformal prediction.

```python
# probabilistic regression model (with quantiles)
model = LinearRegressionModel(
    lags=input_length,
    output_chunk_length=horizon,
    likelihood="quantile",
    quantiles=quantiles,
).fit(train)

# conformalized quantile regression model
cp_model = ConformalQRModel(model=model, quantiles=quantiles, cal_length=four_weeks)
hfcs = cp_model.historical_forecasts(
    series=cal_test,
    forecast_horizon=horizon,
    start=test.start_time(),
    last_points_only=True,
    stride=horizon,
    **pred_kwargs,
)
plot_historical_forecasts(hfcs)

bt = cp_model.backtest(
    cal_test,
    historical_forecasts=hfcs,
    last_points_only=True,
    metric=[metrics.mic, metrics.miw],
    metric_kwargs={"q_interval": q_interval},
)
pd.DataFrame({"Interval": q_range, "Coverage": bt[0], "Width": bt[1]})
```

--------------------------------

### Install Darts without PyTorch from PyPI

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs the core Darts library with support for Prophet, LightGBM, CatBoost, XGBoost, and StatsForecast, but excludes PyTorch.

```bash
pip install "darts[notorch]"
```

--------------------------------

### Initialize and Backtest NaiveEnsembleModel

Source: https://github.com/unit8co/darts/blob/master/examples/19-EnsembleModel-examples.ipynb

Initializes a NaiveEnsembleModel with NaiveSeasonal and NaiveDrift models and performs historical forecasting. Use this to get a baseline ensemble performance.

```python
naive_ensemble = NaiveEnsembleModel(
    forecasting_models=[NaiveSeasonal(K=12), NaiveDrift()]
)

backtest = naive_ensemble.historical_forecasts(ts_air, start=0.6, forecast_horizon=3)

ts_air.plot(label="series")
backtest.plot(label="prediction")
print("NaiveEnsemble (naive) MAPE:", round(mape(backtest, ts_air), 5))
```

--------------------------------

### Setup and Fine-tune Chronos-2 Model

Source: https://github.com/unit8co/darts/blob/master/examples/27-Torch-and-Foundation-Model-Fine-Tuning-examples.ipynb

Configures and fine-tunes the Chronos-2 model, focusing on specific layers for training. Requires PyTorch backend and includes trainer configurations for gradient clipping and progress bar.

```python
# setup fine-tuning; only tune the layers matching "output_patch_embedding"
model_finetune = Chronos2Model(
    enable_finetuning={"unfreeze": ["output_patch_embedding*"]},
    save_checkpoints=True,
    model_name="chronos",
    force_reset=True,
    optimizer_kwargs={"lr": 1e-3},
    pl_trainer_kwargs=dict(
        check_val_every_n_epoch=5,
        gradient_clip_val=1,
        callbacks=[TFMProgressBar(enable_train_bar_only=True)],
    ),
    **model_params,
)

# fine-tune for 15 epochs
model_finetune.fit(
    series=train_beer,
    val_series=val_beer,
    load_best=True,
    epochs=15,
)

# predict
pred_beer = model_finetune.predict(n=output_chunk_length, series=val_beer)

# hint: you can store the fine-tuned model with `model_finetune.save()`

# plot
series_beer[-3 * output_chunk_length :].plot(label="Ground truth")
pred_beer.plot(
    label="Forecast",
    title=f"Fine-tuned Chronos-2; MAE {mae(series_beer, pred_beer):.2f}",
);
```

--------------------------------

### Initialize TCNModel for Energy Data with Covariates

Source: https://github.com/unit8co/darts/blob/master/examples/05-TCN-examples.ipynb

Initializes a TCNModel for the energy dataset, including past covariates. Note the different `input_chunk_length` and `output_chunk_length` compared to the sunspot example.

```python
model_name = "TCN_energy"
model_en = TCNModel(
    input_chunk_length=365,
    output_chunk_length=7,
    n_epochs=50,
    dropout=0.2,
    dilation_base=2,
    weight_norm=True,
    kernel_size=5,
    num_filters=8,
    nr_epochs_val_period=1,
    random_state=0,
    save_checkpoints=True,
    model_name=model_name,
    force_reset=True,
    **generate_torch_kwargs(),
)
```

--------------------------------

### Configuring Model for TPU Usage

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/gpu_and_tpu_usage.md

To utilize TPUs, set the `accelerator` to 'tpu' and specify the number of `tpu_cores` within the `pl_trainer_kwargs`. This example configures the model to use four TPU cores.

```python
my_model = RNNModel(
    model="RNN",
    ...
    force_reset=True,
    pl_trainer_kwargs={
      "accelerator": "tpu",
      "tpu_cores": [4]
    },
)
```

--------------------------------

### Multi-GPU Training Setup with DDP Spawn

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/gpu_and_tpu_usage.md

When using DDP Spawn for multi-GPU training, ensure your execution is within a separate .py script and protected by the `if __name__ == '__main__':` block. This is necessary even outside of Windows environments.

```python
import torch

if __name__ == '__main__':

    torch.multiprocessing.freeze_support()
```

--------------------------------

### TensorBoard Logging Setup

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Configures a PyTorch Forecasting Model to log training progress with TensorBoard and save model checkpoints. TensorBoard logs are saved to 'darts_logs' by default.

```python
model = SomeTorchForecastingModel(..., log_tensorboad, save_checkpoints=True)
model.fit(...)
```

--------------------------------

### Multi-horizon Forecasts with Conformal Prediction (Model 1)

Source: https://github.com/unit8co/darts/blob/master/examples/23-Conformal-Prediction-examples.ipynb

Generates multi-horizon forecasts with calibrated prediction intervals using a ConformalNaiveModel. This example demonstrates how to set the forecast horizon and plot the actual series against the predicted intervals.

```python
multi_horizon = 24
pred = cp_model.predict(n=multi_horizon, series=cal, **pred_kwargs)

# plot
ax = series[pred.start_time() - 7 * 24 * series.freq : pred.end_time()].plot(
    label="actual"
)
pred.plot()
```

--------------------------------

### Initialize, Fit, and Predict with NaiveSeasonal

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/forecasting_overview.md

Demonstrates the basic workflow of fitting a model to training data and generating forecasts.

```python
from darts.models import NaiveSeasonal

naive_model = NaiveSeasonal(K=1)            # init
naive_model.fit(train)                      # fit
naive_forecast = naive_model.predict(n=36)  # predict
```

--------------------------------

### Install pyyaml before Darts on Google Colab

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/faq.md

If you encounter issues with recent pyyaml versions on Google Colab, install version 5.4.1 before installing Darts to resolve them.

```python
!pip install pyyaml==5.4.1
```

--------------------------------

### Migrate Darts PyPI Installation (Torch)

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Updates PyPI installation command for Darts version 0.41.0 and above, specifically for users who previously installed Darts with PyTorch support.

```bash
pip install "darts[torch]>=0.41.0"
```

--------------------------------

### TPU Installation for Google Colab

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/gpu_and_tpu_usage.md

Before using TPUs in Google Colab, install the necessary packages, including `cloud-tpu-client`, `torch_xla`, and specific versions of PyTorch, torchvision, and torchtext. Ensure PyYAML is also installed.

```bash
!pip install cloud-tpu-client==0.10 https://storage.googleapis.com/tpu-pytorch/wheels/torch_xla-1.9-cp37-cp37m-linux_x86_64.whl
!pip install torch==1.9.0+cu111 torchvision==0.10.0+cu111 torchtext==0.10.0 -f https://download.pytorch.org/whl/cu111/torch_stable.html
!pip install pyyaml==5.4.1
```

--------------------------------

### Initialize, Fit, and Predict with NBEATSModel on Multiple Series

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/forecasting_overview.md

Shows how to initialize a model and fit it on multiple training series, then predict for different series.

```python
from darts.models import NBEATSModel

model = NBEATSModel(input_chunk_length=24,                 # init
                    output_chunk_length=12)

model.fit([series1, series2])                              # fit on two series
forecast = model.predict(series=[series3, series4], n=36)  # predict potentially different series
```

--------------------------------

### Load and Prepare Sunspots Dataset

Source: https://github.com/unit8co/darts/blob/master/examples/06-Transformer-examples.ipynb

Loads the 'monthly sunspots' dataset, plots it, checks for seasonality, splits it into training and validation sets, and scales the data. Ensure the dataset is loaded and preprocessed before training.

```python
series_sunspot = SunspotsDataset().load().astype(np.float32)

series_sunspot.plot()
check_seasonality(series_sunspot, max_lag=240)

train_sp, val_sp = series_sunspot.split_after(pd.Timestamp("19401001"))

scaler_sunspot = Scaler()
train_sp_scaled = scaler_sunspot.fit_transform(train_sp)
val_sp_scaled = scaler_sunspot.transform(val_sp)
series_sp_scaled = scaler_sunspot.transform(series_sunspot)
```

--------------------------------

### Initialize and Run Ray Tune Tuner

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/hyperparameter_optimization.md

Creates a Tuner object with the trainable function, hyperparameter space, and configuration, then executes the hyperparameter search.

```python
tuner = Tuner(
    trainable=tune.with_resources(
        train_fn_with_parameters,
        resources=resources_per_trial
    ),
    param_space=config,
    tune_config=tune.TuneConfig(
        metric="MAPE", mode="min", num_samples=num_samples, scheduler=scheduler
    ),
    run_config=RunConfig(name="tune_darts", progress_reporter=reporter),
)
results = tuner.fit()
```

--------------------------------

### Retrain/Finetune with Custom Optimizer

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Initializes a new model with the same architecture but a different optimizer (e.g., SGD) and loads weights from a checkpoint.

```python
# model with identical architecture but different optimizer (default: torch.optim.Adam)
model_finetune = SomeTorchForecastingModel(...,  # use identical parameters & values as in original model
                                           optimizer_cls=torch.optim.SGD,
                                           optimizer_kwargs={"lr": 0.001})

# load the weights from a checkpoint
model_finetune.load_weights_from_checkpoint(model_name='my_model', best=True)

model_finetune.fit(...)
```

--------------------------------

### Initialize TiDE Models

Source: https://github.com/unit8co/darts/blob/master/examples/18-TiDE-examples.ipynb

Initializes NHiTS and TiDE models with common arguments. Demonstrates creating TiDE models with and without reversible instance normalization.

```python
model_nhits = NHiTSModel(**common_model_args, model_name="hi")

model_tide = TiDEModel(
    **common_model_args, use_reversible_instance_norm=False, model_name="tide0"
)

model_tide_rin = TiDEModel(
    **common_model_args, use_reversible_instance_norm=True, model_name="tide1"
)

models = {
    "NHiTS": model_nhits,
    "TiDE": model_tide,
    "TiDE+RIN": model_tide_rin,
}
```

--------------------------------

### Install Darts with PyTorch from Conda-Forge

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs Darts with PyTorch support from conda-forge and PyTorch channels. This command assumes the conda environment is already activated.

```bash
conda install -c conda-forge -c pytorch u8darts-torch
```

--------------------------------

### Install All Darts Models from Conda-Forge

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs Darts with all available model dependencies from conda-forge and PyTorch channels. This command assumes the conda environment is already activated.

```bash
conda install -c conda-forge -c pytorch u8darts-all
```

--------------------------------

### Install Darts Core from Conda-Forge

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs the core Darts library from conda-forge without optional dependencies. This command assumes the conda environment is already activated.

```bash
conda install -c conda-forge u8darts
```

--------------------------------

### Fit and Predict with ExponentialSmoothing and LightGBM Models

Source: https://context7.com/unit8co/darts/llms.txt

Demonstrates the unified fit() and predict() interface for both classical (ExponentialSmoothing) and machine learning (LightGBM) models. LightGBMModel requires specifying lags and output_chunk_length.

```python
from darts.datasets import AirPassengersDataset
from darts.models import ExponentialSmoothing, LightGBMModel
from darts import metrics

series = AirPassengersDataset().load()       # 144 monthly observations
train, test = series[:-24], series[-24:]    # last 2 years as test

# --- Classical / local model ---
es_model = ExponentialSmoothing()
es_model.fit(train)
es_pred = es_model.predict(n=24)
print(f"ExponentialSmoothing MAE: {metrics.mae(test, es_pred):.2f}")

# --- ML / global model with lag features ---
lgbm_model = LightGBMModel(lags=12, output_chunk_length=12)
lgbm_model.fit(train)
lgbm_pred = lgbm_model.predict(n=24, series=train)
print(f"LightGBM MAE: {metrics.mae(test, lgbm_pred):.2f}")
```

```python
from darts.models import RNNModel
rnn = RNNModel(
    model="LSTM",
    hidden_dim=20,
    dropout=0.0,
    batch_size=16,
    n_epochs=10,
    training_length=20,
    input_chunk_length=12,
    likelihood=None,
    random_state=42,
)
rnn.fit(train, verbose=False)
pred_prob = rnn.predict(n=12, num_samples=500)
print(pred_prob.shape)  # (12, 1, 500)
low  = pred_prob.quantile_timeseries(0.05)
high = pred_prob.quantile_timeseries(0.95)
```

--------------------------------

### Install Darts without PyTorch from Conda-Forge

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Installs Darts with support for Prophet, LightGBM, CatBoost, XGBoost, and StatsForecast from conda-forge, excluding PyTorch. This command assumes the conda environment is already activated.

```bash
conda install -c conda-forge u8darts-notorch
```

--------------------------------

### Fit and Predict with NaiveSeasonal (K=1)

Source: https://github.com/unit8co/darts/blob/master/examples/00-quickstart.ipynb

Demonstrates fitting a NaiveSeasonal model with K=1 to training data and making a 36-step forecast. Useful for establishing a baseline accuracy.

```python
from darts.models import NaiveSeasonal

naive_model = NaiveSeasonal(K=1)
naive_model.fit(train)
naive_forecast = naive_model.predict(36)

series.plot(label="actual")
naive_forecast.plot(label="naive forecast (K=1)");
```

--------------------------------

### Multiple Series Forecasting Setup

Source: https://github.com/unit8co/darts/blob/master/examples/26-NeuralForecast-examples.ipynb

Prepares data for multiple time series forecasting by splitting a multivariate series into two univariate series and repeating covariates. This setup is used for global training and forecasting on multiple series.

```python
# split the multivariate series into two (multiple) univariate series
series_multiple = [series_multivar["#Passengers"], series_multivar["#Passengers_1"]]
series_multiple_train = [s[:-output_chunk_length] for s in series_multiple]

# since the covariates apply to both series, we can simply repeat them
future_covariates_multiple = [future_covariates] * len(series_multiple)

# get a fresh model instance
model = model.untrained_model()

# fit and predict
model.fit(
    series=series_multiple_train,
    future_covariates=future_covariates_multiple,
)
forecasts = model.predict(
    n=output_chunk_length,
    series=series_multiple_train,
    future_covariates=future_covariates_multiple,
)

```

--------------------------------

### Run Optuna Optimization Study

Source: https://github.com/unit8co/darts/blob/master/examples/17-hyperparameter-optimization.ipynb

This code sets up and runs an Optuna optimization study. It creates a study object, defines a callback function to print progress, and then optimizes the objective function for a specified timeout. An alternative for limiting the number of trials is also commented out.

```python
def print_callback(study, trial):
    print(f"Current value: {trial.value}, Current params: {trial.params}")
    print(f"Best value: {study.best_value}, Best params: {study.best_trial.params}")


study = optuna.create_study(direction="minimize")

study.optimize(objective, timeout=7200, callbacks=[print_callback])

# We could also have used a command as follows to limit the number of trials instead:
# study.optimize(objective, n_trials=100, callbacks=[print_callback])
```

--------------------------------

### Retrain/Finetune with Custom LR Scheduler

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Initializes a new model with the same architecture but a custom learning rate scheduler and loads weights from a manual save.

```python
# model with identical architecture but different lr scheduler (default: None)
model_finetune = SomeTorchForecastingModel(...,  # use identical parameters & values as in original model
                                           lr_scheduler_cls=torch.optim.lr_scheduler.ExponentialLR,
                                           lr_scheduler_kwargs={"gamma": 0.09})

# load the weights from a manual save
model_finetune.load_weights("/your/path/to/save/model.pt")
```

--------------------------------

### Export TorchForecastingModel to ONNX

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Exports a trained TorchForecastingModel to the ONNX format for lightweight inference. Requires `onnx` and `onnxruntime` to be installed.

```python
model = SomeTorchForecastingModel(...)
model.fit(...)

# make sure to have `onnx` and `onnxruntime` installed
onnx_filename = "example_onnx.onnx"
model.to_onnx(onnx_filename, export_params=True)
```

--------------------------------

### Generate Explanations

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Generate the explanations using the explain() method. You can optionally pass a custom foreground series to explain, or explain the background series by default.

```python
explainability_result = explainer.explain()
```

--------------------------------

### Instantiate TFTExplainer

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Instantiate the TFTExplainer. You can either pass a custom background series or let the explainer load it automatically from the model if it was trained on a single target series.

```python
explainer = TFTExplainer(my_model_ice)
```

--------------------------------

### Create Shifted Forecast Model

Source: https://github.com/unit8co/darts/blob/master/examples/00-quickstart.ipynb

Use `output_chunk_shift` to create forecasts starting at a future offset. This model cannot perform auto-regression.

```python
model_shifted = LinearRegressionModel(
    lags=12,
    lags_future_covariates=(0, 12),
    output_chunk_length=12,
    output_chunk_shift=12,
)

model_shifted.fit(series_air[:-24], future_covariates=air_covs)
preds = model_shifted.predict(n=12)

series_air[:-24].plot(label="train series")
series_air[-24:].plot(label="val_series")
preds.plot(label="shifted prediction");
```

--------------------------------

### Load Air Passengers Dataset

Source: https://github.com/unit8co/darts/blob/master/examples/00-quickstart.ipynb

Load the built-in Air Passengers dataset into a TimeSeries object. This is useful for quick testing and examples.

```python
from darts.datasets import AirPassengersDataset

series = AirPassengersDataset().load()
series.plot();
```

--------------------------------

### Import Libraries and Configure Logging

Source: https://github.com/unit8co/darts/blob/master/examples/07-NBEATS-examples.ipynb

Imports necessary libraries for time-series analysis and model implementation, and configures logging and warnings.

```python
import warnings

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from darts import TimeSeries, concatenate
from darts.dataprocessing.transformers import MissingValuesFiller, Scaler
from darts.datasets import EnergyDataset
from darts.metrics import r2_score
from darts.models import NBEATSModel
from darts.utils.callbacks import TFMProgressBar

warnings.filterwarnings("ignore")
import logging

logging.disable(logging.CRITICAL)
```

--------------------------------

### Import Libraries and Configure Plotting

Source: https://github.com/unit8co/darts/blob/master/examples/05-TCN-examples.ipynb

Imports necessary libraries, sets up plotting style, and configures logging.

```python
%matplotlib inline

import warnings

import matplotlib.pyplot as plt
import pandas as pd

# use darts plotting style
from darts import set_option

set_option("plotting.use_darts_style", True)

from darts import TimeSeries, concatenate
from darts.dataprocessing.transformers import Scaler
from darts.datasets import AirPassengersDataset, EnergyDataset, SunspotsDataset
from darts.models import TCNModel
from darts.utils.callbacks import TFMProgressBar
from darts.utils.missing_values import fill_missing_values
from darts.utils.timeseries_generation import datetime_attribute_timeseries

warnings.filterwarnings("ignore")

import logging

logging.disable(logging.CRITICAL)


def generate_torch_kwargs():
    # run torch models on CPU, and disable progress bars for all model stages except training.
    return {
        "pl_trainer_kwargs": {
            "accelerator": "cpu",
            "callbacks": [TFMProgressBar(enable_train_bar_only=True)],
        }
    }

```

--------------------------------

### Get Static Covariates Importance Values

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Retrieve the static covariates importance values. This is only applicable if the model was trained with static covariates.

```python
explainability_result.get_static_covariates_importance()
```

--------------------------------

### Import TFTExplainer

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Import the TFTExplainer class from the darts.explainability module. This is the first step to using the explainer.

```python
from darts.explainability import TFTExplainer
```

--------------------------------

### Pull Latest Darts Docker Image

Source: https://github.com/unit8co/darts/blob/master/INSTALL.md

Pulls the most recent Darts Docker image from the Docker Hub. Ensure Docker is installed and running.

```bash
docker pull unit8/darts:latest
```

--------------------------------

### Viewing TensorBoard Logs

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Command to launch TensorBoard for visualizing training logs stored in the 'darts_logs' directory.

```bash
tensorboad --log_dir darts_logs
```

--------------------------------

### Initialize and Predict with NaiveEnsembleModel

Source: https://github.com/unit8co/darts/blob/master/examples/19-EnsembleModel-examples.ipynb

Initializes a NaiveEnsembleModel with pre-trained forecasting models. Set `train_forecasting_models=False` to use existing models directly for prediction without further training.

```python
naive_ensemble = NaiveEnsembleModel(
    forecasting_models=[tcn_model, linreg_model], train_forecasting_models=False
)
# NaiveEnsemble initialized with pre-trained models can call predict() directly,
# the `series` argument must however be provided
pred_naive = naive_ensemble.predict(len(val), train)
```

--------------------------------

### Train Linear Regression Model

Source: https://github.com/unit8co/darts/blob/master/examples/19-EnsembleModel-examples.ipynb

Trains a regular Linear Regression model with a specified number of lags. No covariates are used in this basic setup.

```python
linreg_model = LinearRegressionModel(lags=24)
linreg_model.fit(train)
```

--------------------------------

### Create and Backtest Optimized NaiveEnsembleModel

Source: https://github.com/unit8co/darts/blob/master/examples/19-EnsembleModel-examples.ipynb

Initializes a NaiveEnsembleModel with selected high-performing and diverse models (LinearRegressionModel and ExponentialSmoothing) and performs backtesting. This ensemble aims for improved accuracy over individual models.

```python
ensemble = NaiveEnsembleModel(
    forecasting_models=[LinearRegressionModel(lags=12), ExponentialSmoothing()]
)

backtest = ensemble.historical_forecasts(ts_air, start=0.6, forecast_horizon=3)

ts_air[-len(backtest) :].plot(label="series")
backtest.plot(label="prediction")
plt.ylim([250, 650])
print("NaiveEnsemble (v2) MAPE:", round(mape(backtest, ts_air), 5))
```

--------------------------------

### Get Sunspots Dataset Size

Source: https://github.com/unit8co/darts/blob/master/examples/06-Transformer-examples.ipynb

Prints the total number of data points in the 'monthly sun spots' dataset. This is useful for understanding the scale of the dataset.

```python
f"the 'monthly sun spots' dataset has {len(series_sunspot)} data points"
```

--------------------------------

### Load and Preprocess Energy Dataset

Source: https://github.com/unit8co/darts/blob/master/examples/09-DeepTCN-examples.ipynb

Loads the EnergyDataset, preprocesses it by calculating daily averages, filling missing values, and scaling the time series data for model input.

```python
df3 = EnergyDataset().load().to_dataframe()
df3_day_avg = (
    df3.groupby(df3.index.astype(str).str.split(" ").str[0]).mean().reset_index()
)
series_en = fill_missing_values(
    TimeSeries.from_dataframe(
        df3_day_avg, "time", ["generation hydro run-of-river and poundage"]
    ),
    "auto",
)

# scale
scaler_en = Scaler()
train_en, val_en = series_en.split_after(pd.Timestamp("20170901"))
train_en_transformed = scaler_en.fit_transform(train_en)
val_en_transformed = scaler_en.transform(val_en)
series_en_transformed = scaler_en.transform(series_en)
```

--------------------------------

### Pipeline with Missing Values Filler and Scaler

Source: https://github.com/unit8co/darts/blob/master/examples/02-data-processing.ipynb

Creates a pipeline to fill missing values and then scale the TimeSeries data. Demonstrates the setup for preprocessing incomplete series.

```python
incomplete_series = MonthlyMilkIncompleteDataset().load()

filler = MissingValuesFiller()
scaler = Scaler()

pipeline = Pipeline([filler, scaler])
transformed = pipeline.fit_transform(incomplete_series)
```

--------------------------------

### Save and Load NBEATSModel (Torch Model)

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/forecasting_overview.md

Demonstrates saving and loading a PyTorch-based NBEATSModel, which includes saving training state.

```python
from darts.models import NBEATSModel

model = NBEATSModel(input_chunk_length=24,
                    output_chunk_length=12)

model.save("my_model.pt")
model_loaded = NBEATSModel.load("my_model.pt")
```

--------------------------------

### Get Encoder Importance Values

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Retrieve the encoder feature importance values directly from the explainability result object. This provides numerical insights into feature contributions.

```python
explainability_result.get_encoder_importance()
```

--------------------------------

### Configure Ray Tune Scheduler and Reporter

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/hyperparameter_optimization.md

Sets up the ASHA scheduler for efficient hyperparameter search and the CLI reporter to display progress during the tuning process.

```python
num_samples = 10

scheduler = ASHAScheduler(max_t=1000, grace_period=3, reduction_factor=2)

reporter = CLIReporter(
    parameter_columns=list(config.keys()),
    metric_columns=["loss", "MAPE", "training_iteration"],
)
```

--------------------------------

### Create Multivariate Time Series

Source: https://github.com/unit8co/darts/blob/master/examples/26-NeuralForecast-examples.ipynb

Generates a multivariate time series by stacking two univariate series derived from an existing series. This is a prerequisite for multivariate forecasting examples.

```python
# generate a multivariate series
series_multivar = series.stack(series * -1 + series.max(axis=0))
series_multivar.plot(title="Multivariate Series");
```

--------------------------------

### Initialize and Train N-BEATS Model

Source: https://github.com/unit8co/darts/blob/master/examples/14-transfer-learning.ipynb

Initializes a N-BEATS model with specified parameters and trains it on the M4 training data. Ensure to set the 'accelerator' to 'gpu' if a GPU is available.

```python
np.random.seed(42)
torch.manual_seed(42)

nbeats_model_m4 = NBEATSModel(
    input_chunk_length=IN_LEN,
    output_chunk_length=OUT_LEN,
    batch_size=BATCH_SIZE,
    num_stacks=NUM_STACKS,
    num_blocks=NUM_BLOCKS,
    num_layers=NUM_LAYERS,
    layer_widths=LAYER_WIDTH,
    expansion_coefficient_dim=COEFFS_DIM,
    loss_fn=SmapeLoss(),
    optimizer_kwargs={"lr": LR},
    pl_trainer_kwargs={
        "enable_progress_bar": True,
        # change this one to "gpu" if your notebook does run in a GPU environment:
        "accelerator": "cpu",
    },
)

# Train
nbeats_model_m4.fit(
    m4_train,
    dataloader_kwargs={"num_workers": 4},
    epochs=NUM_EPOCHS,
    max_samples_per_ts=MAX_SAMPLES_PER_TS,
)
```

--------------------------------

### Initialize TSMixer and TiDE Models

Source: https://github.com/unit8co/darts/blob/master/examples/21-TSMixer-examples.ipynb

Initializes TSMixer and TiDE models with specified parameters. These models are suitable for time series forecasting tasks.

```python
model_tsm = TSMixerModel(
    **create_params(
        input_chunk_length,
        output_chunk_length,
        full_training=full_training,
    ),
    use_static_covariates=use_static_covariates,
    model_name="tsm",
)
model_tide = TiDEModel(
    **create_params(
        input_chunk_length,
        output_chunk_length,
        full_training=full_training,
    ),
    use_static_covariates=use_static_covariates,
    model_name="tide",
)

models = {
    "TSM": model_tsm,
    "TiDE": model_tide,
}
```

--------------------------------

### N-BEATS Hyper-parameters Configuration

Source: https://github.com/unit8co/darts/blob/master/examples/14-transfer-learning.ipynb

Defines hyper-parameters for an N-BEATS model, including input/output lengths, architecture details, and training settings. These parameters serve as a starting point for training.

```python
### Possible N-BEATS hyper-parameters

# Slicing hyper-params:
IN_LEN = 30
OUT_LEN = 4

# Architecture hyper-params:
NUM_STACKS = 20
NUM_BLOCKS = 1
NUM_LAYERS = 2
LAYER_WIDTH = 136
COEFFS_DIM = 11

# Training settings:
LR = 1e-3
BATCH_SIZE = 1024
MAX_SAMPLES_PER_TS = 10
NUM_EPOCHS = 10
```

--------------------------------

### Get Decoder Importance Values

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Retrieve the decoder feature importance values directly from the explainability result object. This shows the importance of future covariates in the output chunk.

```python
explainability_result.get_decoder_importance()
```

--------------------------------

### Load and Preprocess Energy Dataset

Source: https://github.com/unit8co/darts/blob/master/examples/08-DeepAR-examples.ipynb

Loads the EnergyDataset, calculates daily averages, fills missing values, and splits the series into training and validation sets.

```python
df3 = EnergyDataset().load().to_dataframe()
df3_day_avg =
    df3.groupby(df3.index.astype(str).str.split(" ").str[0]).mean().reset_index()
series_en = fill_missing_values(
    TimeSeries.from_dataframe(
        df3_day_avg, "time", ["generation hydro run-of-river and poundage"]
    ),
    "auto",
)

# convert to float32
series_en = series_en.astype(np.float32)

# create train and test splits
train_en, val_en = series_en.split_after(pd.Timestamp("20170901"))

# scale
scaler_en = Scaler()
train_en_transformed = scaler_en.fit_transform(train_en)
val_en_transformed = scaler_en.transform(val_en)
series_en_transformed = scaler_en.transform(series_en)
```

--------------------------------

### Implementing a Custom Regression Model

Source: https://github.com/unit8co/darts/blob/master/examples/20-SKLearnModel-examples.ipynb

Defines and uses a custom regression model with `fit` and `predict` methods within Darts' SKLearnModel. This example uses a weighted average approach.

```python
class CustomRegressionModel:
    def __init__(self, weights: np.ndarray):
        """Barebone weighted average"""
        self.weights = weights
        self.norm_coef = sum(weights)

    def fit(self, X: np.ndarray, y: np.ndarray, *args, **kwargs):
        return self

    def predict(self, X: np.ndarray):
        """Apply weights on each sample"""
        return (
            np.stack([np.correlate(x, self.weights, mode="valid") for x in X])
            / self.norm_coef
        )

    def get_params(self, deep: bool):
        return {"weights": self.weights}


window_weights = np.arange(1, 25, 1) ** 2
model = SKLearnModel(
    lags=24,
    output_chunk_length=24,
    model=CustomRegressionModel(window_weights),
    multi_models=False,
)
model.fit(ts_energy_train)
pred = model.predict(n=24)

ts_energy_train[-48:].plot(label="training")
ts_energy_val[:24].plot(label="validation")
pred.plot(label="forecast")
```

--------------------------------

### Create TFT Model for Quantile Regression

Source: https://github.com/unit8co/darts/blob/master/examples/13-TFT-examples.ipynb

Initializes a TFTModel for quantile regression forecasting. This model requires future covariates and is configured with specific input/output lengths, network architecture, and dropout rate.

```python
quantiles = [
    0.01, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 0.99,
]
input_chunk_length = 24
forecast_horizon = 12
my_model = TFTModel(
    input_chunk_length=input_chunk_length,
    output_chunk_length=forecast_horizon,
    hidden_size=64,
    lstm_layers=1,
    num_attention_heads=4,
    dropout=0.1,
    batch_size=16,
    n_epochs=300,
    add_relative_index=False,
    add_encoders=None,
    likelihood=QuantileRegression(
        quantiles=quantiles
    ),  # QuantileRegression is set per default
    # loss_fn=MSELoss(),
    random_state=42,
)
```

--------------------------------

### Fit and Predict with NaiveDrift and Combine Forecasts

Source: https://github.com/unit8co/darts/blob/master/examples/00-quickstart.ipynb

Fits a NaiveDrift model to capture trends and combines its forecast with a seasonal forecast. The combined forecast is adjusted to start at the correct offset.

```python
from darts.models import NaiveDrift

drift_model = NaiveDrift()
drift_model.fit(train)
drift_forecast = drift_model.predict(36)

combined_forecast = drift_forecast + seasonal_forecast - train.last_value()

series.plot()
combined_forecast.plot(label="combined")
drift_forecast.plot(label="drift");
```

--------------------------------

### Generate Synthetic Univariate Time Series Data

Source: https://github.com/unit8co/darts/blob/master/examples/22-anomaly-detection-examples.ipynb

Generates a synthetic univariate time series with specified starting value and random state, applying bounds and random differences.

```python
def generate_data_ex2(start_val: int, random_state: int):
    np.random.seed(random_state)
    # create the test set
    vals = np.zeros(100)

    vals[0] = start_val

    diffs = np.random.choice(a=[-1, 1], p=[0.5, 0.5], size=len(vals) - 1)
    for i in range(1, len(vals)):
        vals[i] = vals[i - 1] + diffs[i - 1]
        if vals[i] > 3:
            vals[i] = 3
        elif vals[i] < 0:
            vals[i] = 0
    return vals
```

--------------------------------

### Load and Predict with a TorchForecastingModel

Source: https://github.com/unit8co/darts/blob/master/docs/userguide/torch_forecasting_models.md

Loads a pretrained TorchForecastingModel from a checkpoint and performs inference. Ensures the model is on the CPU.

```python
loaded_model = SomeTorchForecastingModel.load_from_checkpoint(model_name='my_model',
                                                              best=True,
                                                              map_location="cpu")
loaded_model.to_cpu()

# run inference
loaded_model.predict(...)
```

--------------------------------

### Initialize and Fit KMeansScorer

Source: https://github.com/unit8co/darts/blob/master/examples/22-anomaly-detection-examples.ipynb

Initializes KMeansScorer with specified parameters and fits it on the training time series.

```python
Kmeans_scorer = KMeansScorer(k=2, window=1, component_wise=False)

# fit the KmeansScorer on the train timeseries 'series_train'
Kmeans_scorer.fit(series_train)
```

--------------------------------

### GPU Availability Check

Source: https://github.com/unit8co/darts/blob/master/examples/00-quickstart.ipynb

Checks and reports the availability and usage of GPU (mps) and TPU resources. This is typically part of the Darts library's internal logging during model training or setup.

```text
GPU available: True (mps), used: True
TPU available: False, using: 0 TPU cores
HPU available: False, using: 0 HPUs
```