[ENH] Add TimeSeries datatype as per new API

.github/workflows/test.yml

@@ -5,9 +5,9 @@ name: Test
 
 on:
   push:
-    branches: [main]
+    branches: [v2-dev]
   pull_request:
-    branches: [main]
+    branches: [v2-dev]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

pytorch_forecasting/__init__.py

@@ -9,7 +9,9 @@
     GroupNormalizer,
     MultiNormalizer,
     NaNLabelEncoder,
+    TimeSeries,
     TimeSeriesDataSet,
+    TimeSeriesMetadata,
 )
 from pytorch_forecasting.metrics import (
     MAE,
@@ -66,7 +68,9 @@
 from pytorch_forecasting.utils._maint._show_versions import show_versions
 
 __all__ = [
+    "TimeSeries",
     "TimeSeriesDataSet",
+    "TimeSeriesMetadata",
     "GroupNormalizer",
     "EncoderNormalizer",
     "NaNLabelEncoder",

pytorch_forecasting/data/__init__.py

@@ -6,6 +6,7 @@
 into model-ready PyTorch datasets.
 """
 
+from pytorch_forecasting.data._metadata import TimeSeriesMetadata
 from pytorch_forecasting.data.encoders import (
     EncoderNormalizer,
     GroupNormalizer,
@@ -19,6 +20,7 @@
 __all__ = [
     "TimeSeriesDataSet",
     "TimeSeries",
+    "TimeSeriesMetadata",
     "NaNLabelEncoder",
     "GroupNormalizer",
     "TorchNormalizer",

pytorch_forecasting/data/_metadata.py

@@ -0,0 +1,63 @@
+"""Typed schemas of the data layer."""
+
+from dataclasses import dataclass, fields
+
+
+class _DictLike:
+    """Mapping protocol for the metadata dataclasses."""
+
+    def __getitem__(self, key):
+        if key not in self:
+            raise KeyError(key)
+        return getattr(self, key)
+
+    def get(self, key, default=None):
+        return getattr(self, key) if key in self else default
+
+    def keys(self):
+        return [f.name for f in fields(self)]
+
+    def __contains__(self, key):
+        return key in self.keys()
+
+    def __iter__(self):
+        return iter(self.keys())
+
+
+@dataclass(frozen=True)
+class TimeSeriesMetadata(_DictLike):
+    """Schema of a :class:`~pytorch_forecasting.data.TimeSeries`.
+
+    Parameters
+    ----------
+    cols : dict
+        ``{"y": [...], "x": [...], "st": [...]}``, names of the target, feature
+        and static columns. List order is the column order of the corresponding
+        tensor dimension, and must not be reordered.
+    col_type : dict
+        maps column name to ``"F"`` (numerical) or ``"C"`` (categorical).
+    col_known : dict
+        maps column name to ``"K"`` (known in the future) or ``"U"`` (unknown).
+    is_prediction : bool, default=False
+        whether the described object holds predictions rather than input data.
+    """
+
+    cols: dict[str, list[str]]
+    col_type: dict[str, str]
+    col_known: dict[str, str]
+    is_prediction: bool = False
+
+    def __post_init__(self):
+        """Validation checks.
+
+        Raises
+        ------
+        ValueError
+            If ``cols`` does not have exactly the keys ``"y"``, ``"x"``, ``"st"``.
+        """
+        missing = {"y", "x", "st"} - set(self.cols)
+        if missing:
+            raise ValueError(
+                f"`cols` is missing required keys: {sorted(missing)}. It must "
+                'map "y", "x" and "st" to lists of column names.'
+            )