Implementation:Sktime Pytorch forecasting TimeSeries V2

Knowledge Sources	Sktime_Pytorch_forecasting
Domains	Time_Series, Forecasting, Deep_Learning
Last Updated	2026-02-08 08:00 GMT

Overview

TimeSeries is the v2 prototype PyTorch Dataset class for raw time series data ingestion from pandas DataFrames.

Description

TimeSeries extends torch.utils.data.Dataset and serves as the D1 (raw dataset) layer in the v2 pytorch-forecasting data pipeline. It ingests a pandas DataFrame with time series data and converts it into indexed, tensor-based samples keyed by group identifiers. Each sample contains time indices (t), target values (y), features (x), group identifiers, static features (st), and a cutoff time. The class supports optional future data via a separate DataFrame, handles grouping by one or more columns, distinguishes between numerical and categorical features, and tracks which features are known or unknown in the future. Metadata about column types, known/unknown status, and feature organization is computed during initialization and accessible via get_metadata.

Usage

Use TimeSeries as the first layer (D1) when building a v2 pytorch-forecasting pipeline. It wraps a pandas DataFrame for consumption by D2 data modules (TslibDataModule or EncoderDecoderTimeSeriesDataModule). It is experimental and intended for beta testing of the redesigned data architecture.

Code Reference

Source Location

• Repository: Sktime_Pytorch_forecasting
• File: pytorch_forecasting/data/timeseries/_timeseries_v2.py
• Lines: 1-333

Signature

class TimeSeries(Dataset):
    def __init__(
        self,
        data: pd.DataFrame,
        data_future: pd.DataFrame | None = None,
        time: str | None = None,
        target: str | list[str] | None = None,
        group: list[str] | None = None,
        weight: str | None = None,
        num: list[str | list[str]] | None = None,
        cat: list[str | list[str]] | None = None,
        known: list[str | list[str]] | None = None,
        unknown: list[str | list[str]] | None = None,
        static: list[str | list[str]] | None = None,
    ):

__getitem__

def __getitem__(self, index: int) -> dict[str, torch.Tensor]:

get_metadata

def get_metadata(self) -> dict:

Import

from pytorch_forecasting.data.timeseries import TimeSeries

I/O Contract

Constructor Inputs

Name	Type	Required	Description
data	pd.DataFrame	Yes	DataFrame with sequence data; columns must be str
data_future	pd.DataFrame or None	No	DataFrame with future data; may contain only time, group, weight, known, or static columns
time	str or None	No	Integer-typed column denoting time index; defaults to first non-special column
target	str or list[str] or None	No	Column(s) denoting forecasting target; defaults to last column
group	list[str] or None	No	Column names identifying a time series instance; None means single series
weight	str or None	No	Column name for sample weights
num	list[str or list[str]] or None	No	Numerical variable names; defaults to all columns with dtype in "fi"
cat	list[str or list[str]] or None	No	Categorical variable names; defaults to all columns with dtype in "Obc"
known	list[str or list[str]] or None	No	Variables known in the future; defaults to all variables
unknown	list[str or list[str]] or None	No	Variables not known in the future; defaults to no variables
static	list[str or list[str]] or None	No	Variables that do not change over time

__getitem__ Outputs

Name	Type	Description
t	numpy.ndarray	Time index of shape (n_timepoints,)
y	torch.Tensor	Target values of shape (n_timepoints, n_targets)
x	torch.Tensor	Features of shape (n_timepoints, n_features)
group	torch.Tensor	Group identifier of shape (1,)
st	torch.Tensor	Static features tensor
cutoff_time	float	Maximum time index (cutoff) for the series
weights	torch.Tensor	Sample weights of shape (n_timepoints,), only if weight is not None

get_metadata Output

Name	Type	Description
cols	dict	Column names: {'y': list, 'x': list, 'st': list}
col_type	dict[str, str]	Maps column names to 'F' (numerical) or 'C' (categorical)
col_known	dict[str, str]	Maps column names to 'K' (future known) or 'U' (future unknown)

Usage Examples

import pandas as pd
from pytorch_forecasting.data.timeseries import TimeSeries

# Create a simple DataFrame
df = pd.DataFrame({
    "time_idx": list(range(100)) * 2,
    "series_id": ["A"] * 100 + ["B"] * 100,
    "value": range(200),
    "feature_1": range(200),
    "feature_2": range(200),
})

# Create TimeSeries dataset
ts = TimeSeries(
    data=df,
    time="time_idx",
    target="value",
    group=["series_id"],
    num=["feature_1", "feature_2"],
    known=["feature_1"],
    unknown=["feature_2"],
)

# Access a sample
sample = ts[0]
print(sample["t"].shape)      # (100,)
print(sample["y"].shape)      # (100, 1)
print(sample["x"].shape)      # (100, 2)

# Get metadata
meta = ts.get_metadata()
print(meta["cols"]["y"])       # ['value']
print(meta["col_known"])       # {'feature_1': 'K', 'feature_2': 'U', ...}

Related Pages

• Principle:Sktime_Pytorch_forecasting_V2_Data_Pipeline