[ENH] Add TimeSeries datatype as per new API (#2410)

This PR adds the new Add `TimeSeries` datatype and update datamodule
with the new design.
See #2407, #2398

- `TimeSeries` is now a standarised datatype. Updated the tests and
renamed the file to `test_timeseries_v2` as this is no more a D1 layer!

- Also, we now have `metadata` as a dataclass, instead of the `dict` to
make it more user friendly.
Updated tests also updates some old ones (and removes some tests like
`init` checks - which are not needed i think?)

This PR is aimed at `v2-dev` instead of `main`, so that we dont break
current user code until this design is complete and stable. See #2407
for details. So I had to update the branch target in the workflows for
the tests to run (which might fail due to the changes)


## Stack
- `TimeSeries` - #2410         **<- This PR**
- `Datamodule` - #2423 
- `Forecaster` - #2434    


## Note
The tutorials will fail for sure, will update the notebook in one of the
branchs stacked over this PR.
Still need to add the `Forecaster` and tests - will add the notebook and
docs changes on the upcoming branches as the vignette is incomplete
without `forecaster` which is not in this PR.

## Changes made
- Changed the test file of `TimeSeries` from `test_d1` tro
`test_timeseries_v2`
- updates to `TimeSeries`
   - Now uses `TimeSeriesMetadata` as metadata inplace of a `dict`
   - Not a `Dataset` anymore
   - Added some auto-detection of cols
     - `target` is the last column of `data`.
- `time` is the first column not already used as `group`, `target`,
`static` or `weight`. If no such column exists, `ValueError` is raised -
pass `time` explicitly.
- `num` and `cat` are the dtype split over all columns that are not
`group`, `time` or `weight`
   - data validation
   - `to_pandas` to create a df
   - `from_tensors` to create a `TimeSeries` class for predicitons 
- which lack a lot of metadata, so need special handling otherwise will
interfere with the input data validation

Author: phoeenniixx

.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.'
+            )