[ENH] Expose Encoder Scaling Parameters in `TimeSeriesDataSet` + Provide Inverse‑Scaling Utility

[cngmid]

Summary

TimeSeriesDataSet currently applies scaling to encoder continuous variables internally, but the scaling parameters (e.g., means, stds, per‑sample scales) are not exposed in a way that allows users to invert the transformation. This limits interpretability, debugging, and downstream analysis.

I propose adding:

1. Public access to encoder scaling parameters

2. Support for user‑provided per‑feature scalers

3. A clean inverse‑scaling utility that works for both dataset indexing and dataloader batches

I have a working implementation and a demonstration notebook and can open a PR once the design is approved.

---

Motivation

Many forecasting workflows require inspecting model inputs and outputs in the original data space.

Currently:

• TimeSeriesDataSet applies scaling (e.g., EncoderNormalizer, StandardScaler, or custom scalers) to real inputs, but the resulting scale parameters are not exposed in a structured way

• Users cannot reliably invert the transformation for encoder continuous variables.

This makes it difficult to:

• debug model behavior

• visualize inputs/outputs

• compare predictions to raw data

---

Proposed Enhancement

1. Expose encoder scaling parameters

For each continuous variable, expose:

• the computed scale parameters (if using internal normalizers)

• the index mapping between features and scale tensors

This could be added as attributes on the dataset, e.g.:

    def __getitem__():
        ...
        return (
            dict(
                x_cat=data_cat,
                x_cont=data_cont,
                encoder_length=encoder_length,
                decoder_length=decoder_length,
                encoder_target=encoder_target,
                encoder_time_idx_start=time[0],
                groups=groups,
                target_scale=target_scale,
                
                # add input scales as tensors
                x_scale_idx=data_scale_idx,
                x_scale=data_scale,
            ),
            (target, weight),
        )

and on the dataloader:

    def _collate_fn()
        ...
        return (
            dict(
                encoder_cat=encoder_cat,
                encoder_cont=encoder_cont,
                encoder_target=encoder_target,
                encoder_lengths=encoder_lengths,
                decoder_cat=decoder_cat,
                decoder_cont=decoder_cont,
                decoder_target=target,
                decoder_lengths=decoder_lengths,
                decoder_time_idx=decoder_time_idx,
                groups=groups,
                target_scale=target_scale,
                
                # add encoder scale
                encoder_scale_idx=encoder_scale_idx,
                encoder_scale=encoder_scale,
            ),
            (target, weight),
        )

2. Provide an inverse‑scaling utility (optional)

A function such as TimeSeriesDataSet.inverse_transform(batch_or_item) that handles:

• StandardScaler

• EncoderNormalizer

• per‑sample scale parameters

• both dataset indexing and dataloader batches

I have implemented a working version and validated it across all cases.

---

Example Notebook

I prepared a small notebook demonstrating:

• a toy dataset with mixed scaling

• a modified TimeSeriesDataSet supporting per‑feature scalers

• a robust inverse‑scaling function

• validation that inverse‑scaling reconstructs the original data

• correct behavior for both dataset items and dataloader batches

I can attach the notebook if helpful.

---

Benefits

• Enables full interpretability of model inputs/outputs

• Makes debugging significantly easier

• Provides a clean API for advanced users

• No breaking changes to existing code

---

Request

Please let me know whether the proposed API direction aligns with project goals.

I’m happy to refine the design based on your feedback and/or submit a PR.

[phoeenniixx]

Hi @cngmid! I think this would be a good addition! Thanks a lot for proposing this.
Can you please share some examples how this would look like?
Would you like to work on this (or help in reviews), if you have some time for this?

[cngmid]

I have attached a notebook as an example. I would be happy to create a PR and help in reviews.

1. Creating a TimeSeriesDataSet with mixed per‑feature scalers

Create a small synthetic dataset with noise.
This makes it easy to verify that inverse-scaling reconstructs the original data.

The data consists in two (n_assets) time series of length eight (n_times) with four (n_covariates) covariates.

Define a TimeSeriesDataSet with mixed scaling strategies:

• Two unscaled features.

• One feature using sklearn StandardScaler

• Two (n_scalers) features using EncoderNormalizer

This setup allows us to test whether inverse-scaling works for all cases.

The encoding length is four (in_steps) and the prediction length is two (out_steps).

---

2. Accessing encoder scaling parameters from the dataset

The datatset has 6 elements (n_assets * (n_times + 1 - in_steps - out_steps)).
A dataset element is a dictionary of torch.Tensor and a pair of torch.Tensor.

After the dataset is built, the following attributes become available. Notice the two additional keys:

• x_scale_idx (n_scalers,): mapping from feature index → scale index, and

• x_scale (n_scalers, 2): tensor of per-feature (center, scale) values.

Dataset size: 6

x_cat torch.Size([6, 0]) torch.int64
x_cont torch.Size([6, 5]) torch.float32
encoder_length 4
decoder_length 2
encoder_target torch.Size([4]) torch.float32
encoder_time_idx_start tensor(0)
groups torch.Size([1]) torch.int64
target_scale (2,) float32
x_scale_idx torch.Size([2]) torch.int64
x_scale torch.Size([2, 2]) torch.float32
y torch.Size([2])
w None

---

3. Inverse‑transforming a dataset item
   Transform a dataset continuous encoder element into its original (unscaled) values.

# use the new dataset_inverse_transform() function
x_cont_original = dataset_inverse_transform(
    self,
    x['x_cont'],
    x['target_scale'],
    x['x_scale_idx'],
    x['x_scale']
)

Validation: reconstructed values match the original data

Compare inverse-transformed values to original data.

---

4. Accessing encoder scaling parameters from a dataloader

The dataloader has 2 elements (len(self) / batch_size).
A dataloader element is a dictionary of torch.Tensor and a pair of torch.Tensor.

After the dataset is built, the following attributes become available. Notice the two additional keys:

• encoder_scale_idx (batch_size, n_scalers,): mapping from feature index → scale index, and

• encoder_scale (batch_size, n_scalers, 2): tensor of per-feature (center, scale) values.

Dataloader size: 2

encoder_cat torch.Size([3, 4, 0]) torch.int64
encoder_cont torch.Size([3, 4, 5]) torch.float32
encoder_target torch.Size([3, 4]) torch.float32
encoder_lengths torch.Size([3]) torch.int64
decoder_cat torch.Size([3, 2, 0]) torch.int64
decoder_cont torch.Size([3, 2, 5]) torch.float32
decoder_target torch.Size([3, 2]) torch.float32
decoder_lengths torch.Size([3]) torch.int64
decoder_time_idx torch.Size([3, 2]) torch.int64
groups torch.Size([3, 1]) torch.int64
target_scale torch.Size([3, 2]) torch.float32
encoder_scale_idx torch.Size([3, 2]) torch.int64
encoder_scale torch.Size([3, 2, 2]) torch.float32
y torch.Size([3, 2])
w None

---

5. Inverse‑transforming a dataloader item

Transform a dataloader continuous encoder element into its original (unscaled) values.

# use the *same* new dataset_inverse_transform() function
encoder_cont_original = dataset_inverse_transform(
    dataloader.dataset,
    x['encoder_cont'],
    x['target_scale'],
    x['encoder_scale_idx'],
    x['encoder_scale']
)

Validation: reconstructed values match the original data

Compare inverse-transformed values to original data.

ENH - pytorch_forecasting TimeSeriesDataSet dataset with encoder scaling parameters.ipynb

[andersendsa]

Hi @cngmid can i work on this issue

[phoeenniixx]

Hi @cngmid, please raise a PR if you want, or maybe work with @andersendsa on this. Please move ahead as both you want!
(please make sure to add the example somewhere - maybe in one of the tutorials or create a new one)

[cngmid]

Hi @andersendsa — absolutely, happy to collaborate!

Since I already have a working implementation and a demonstration notebook, I can open the initial PR so we have a concrete code path to discuss. Once the PR is up, we can coordinate on:

• refining the API

• adding tests

• improving documentation

• integrating the example notebook into the tutorials

If you have specific ideas or want to take ownership of certain parts (e.g., tests or docs), I’m very open to dividing the work.
Looking forward to working together on this!