handle static covariates timeseries (#2996)

* handle static covariates timeseries

* update changelog

* Update timeseries.py

* Update darts/timeseries.py

Co-authored-by: Jakub Chłapek <147340544+jakubchlapek@users.noreply.github.com>

* minor updates

---------

Co-authored-by: Jakub Chłapek <147340544+jakubchlapek@users.noreply.github.com>
Co-authored-by: dennisbader <dennis.bader@gmx.ch>

Author: 3 people

CHANGELOG.md

@@ -11,6 +11,7 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 
 **Improved**
 
+- `TimeSeries.to_json()` and `from_json()` now support serialization and deserialization of static covariates, metadata, and hierarchy. The optional parameters in `from_json()` can still be used to override or provide these values if they are not present in the JSON string. [#2996](https://github.com/unit8co/darts/pull/2996) by [Tiberiu Sabau](https://github.com/tibisabau).
 - Added new time aggregated metric `autc()` (Area Under Tolerance Curve): The tolerance curve gives the fraction of predicted target values within tolerance bands of the actual target values across a range of tolerances (defined as % of target range). The AUTC is the normalized area under this tolerance curve and given as a score between [0, 1]. Higher scores are better. [#2994](https://github.com/unit8co/darts/pull/2994) by [Jakub Chłapek](https://github.com/jakubchlapek)
 - Added new plotting function `darts.utils.statistics.plot_tolerance_curve()` to plot the tolerance curve described above. [#2994](https://github.com/unit8co/darts/pull/2994) by [Jakub Chłapek](https://github.com/jakubchlapek)
 - Added `TimeSeries.plotly()` method for interactive time series visualization using Plotly backend. [#2977](https://github.com/unit8co/darts/pull/2977) by [Dustin Brunner](https://github.com/brunnedu).

darts/tests/test_timeseries_static_covariates.py

@@ -130,7 +130,10 @@ def test_ts_from_x(self, tag, tmpdir_module):
             tag, ts, TimeSeries.from_csv(f_csv, time_col="time", **kwargs)
         )
         self.helper_test_transfer(tag, ts, TimeSeries.from_pickle(f_pkl))
+        # Test with kwargs (backward compatibility)
         self.helper_test_transfer(tag, ts, TimeSeries.from_json(ts_json, **kwargs))
+        # Test without kwargs (new automatic serialization)
+        self.helper_test_transfer(tag, ts, TimeSeries.from_json(ts_json))
 
     def test_invalid_metadata(self):
         ts = linear_timeseries(length=10)
@@ -965,3 +968,146 @@ def helper_test_transfer_values(tag, ts, ts_new):
             )
         else:  # metadata
             assert ts_new.metadata == ts.metadata
+
+
+class TestTimeSeriesJSONSerialization:
+    """Test JSON serialization with static_covariates, metadata, and hierarchy."""
+
+    def test_json_with_static_covariates(self):
+        """Test that static covariates are preserved in JSON serialization."""
+        ts = linear_timeseries(length=10)
+        static_cov = pd.Series([0.0, 1.0], index=["st1", "st2"])
+        ts = ts.with_static_covariates(static_cov)
+
+        # Serialize and deserialize
+        json_str = ts.to_json()
+        ts_restored = TimeSeries.from_json(json_str)
+
+        # Check that static covariates are preserved
+        assert ts_restored.static_covariates is not None
+        assert ts_restored.static_covariates.equals(ts.static_covariates)
+
+    def test_json_with_metadata(self):
+        """Test that metadata is preserved in JSON serialization."""
+        ts = linear_timeseries(length=10)
+        metadata = {"key1": "value1", "key2": 42, "key3": [1, 2, 3]}
+        ts = ts.with_metadata(metadata)
+
+        # Serialize and deserialize
+        json_str = ts.to_json()
+        ts_restored = TimeSeries.from_json(json_str)
+
+        # Check that metadata is preserved
+        assert ts_restored.metadata is not None
+        assert ts_restored.metadata == ts.metadata
+
+    def test_json_with_hierarchy(self):
+        """Test that hierarchy is preserved in JSON serialization."""
+        components = ["total", "a", "b", "ax", "bx"]
+        hierarchy = {
+            "ax": ["a"],
+            "bx": ["b"],
+            "a": ["total"],
+            "b": ["total"],
+        }
+        ts = TimeSeries.from_values(
+            values=np.random.rand(10, len(components)),
+            columns=components,
+            hierarchy=hierarchy,
+        )
+
+        # Serialize and deserialize
+        json_str = ts.to_json()
+        ts_restored = TimeSeries.from_json(json_str)
+
+        # Check that hierarchy is preserved
+        assert ts_restored.hierarchy is not None
+        assert ts_restored.hierarchy == ts.hierarchy
+        assert ts_restored.top_level_component == ts.top_level_component
+        assert ts_restored.bottom_level_components == ts.bottom_level_components
+
+    def test_json_with_all_attributes(self):
+        """Test JSON serialization with all attributes (static_covariates, metadata, hierarchy)."""
+        components = ["total", "a", "b"]
+        hierarchy = {"a": ["total"], "b": ["total"]}
+        static_cov = pd.DataFrame(
+            [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]],
+            index=components,
+            columns=["sc1", "sc2"],
+        )
+        metadata = {"description": "test series", "version": 1}
+
+        ts = TimeSeries.from_values(
+            values=np.random.rand(10, len(components)),
+            columns=components,
+            hierarchy=hierarchy,
+            static_covariates=static_cov,
+            metadata=metadata,
+        )
+
+        # Serialize and deserialize
+        json_str = ts.to_json()
+        ts_restored = TimeSeries.from_json(json_str)
+
+        # Check all attributes are preserved
+        assert ts_restored.static_covariates is not None
+        assert ts_restored.static_covariates.equals(ts.static_covariates)
+        assert ts_restored.metadata == ts.metadata
+        assert ts_restored.hierarchy == ts.hierarchy
+        assert ts_restored.top_level_component == ts.top_level_component
+        assert ts_restored.bottom_level_components == ts.bottom_level_components
+
+    def test_json_override_attributes(self):
+        """Test that from_json parameters can override JSON-embedded attributes."""
+        components = ["total", "a", "b"]
+        hierarchy = {"a": ["total"], "b": ["total"]}
+        static_cov = pd.DataFrame(
+            [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]],
+            index=components,
+            columns=["sc1", "sc2"],
+        )
+        metadata = {"description": "test series", "version": 1}
+
+        ts = TimeSeries.from_values(
+            values=np.random.rand(10, len(components)),
+            columns=components,
+            hierarchy=hierarchy,
+            static_covariates=static_cov,
+            metadata=metadata,
+        )
+        json_str = ts.to_json()
+
+        # Override with different values
+        new_static_cov = pd.DataFrame(
+            [[10.0, 11.0], [12.0, 13.0], [14.0, 5.0]],
+            index=components,
+            columns=["sc_new1", "sc_new2"],
+        )
+        new_metadata = {"key2": "value2"}
+        new_hierarchy = {"total": ["b"], "b": ["a"]}
+        ts_restored = TimeSeries.from_json(
+            json_str,
+            static_covariates=new_static_cov,
+            metadata=new_metadata,
+            hierarchy=new_hierarchy,
+        )
+
+        # Check that overrides worked
+        # When a Series is passed, it becomes a single-row DataFrame with the series index as columns
+        assert ts_restored.static_covariates is not None
+        assert ts_restored.static_covariates.equals(new_static_cov)
+        assert ts_restored.metadata == new_metadata
+        assert ts_restored.hierarchy == new_hierarchy
+
+    def test_json_without_attributes(self):
+        """Test JSON serialization for series without optional attributes."""
+        ts = linear_timeseries(length=10)
+
+        # Serialize and deserialize
+        json_str = ts.to_json()
+        ts_restored = TimeSeries.from_json(json_str)
+
+        # Check that optional attributes are None
+        assert ts_restored.static_covariates is None
+        assert ts_restored.metadata is None
+        assert ts_restored.hierarchy is None

darts/timeseries.py

@@ -40,6 +40,7 @@
 """
 
 import itertools
+import json
 import math
 import pickle
 import re
@@ -1450,6 +1451,10 @@ def from_json(
 
         At the moment this only supports deterministic time series (i.e., made of 1 sample).
 
+        If the JSON string contains static covariates, hierarchy, or metadata, they will be automatically
+        loaded. The optional parameters `static_covariates`, `hierarchy`, and `metadata` can be used to
+        override or provide these values if they are not present in the JSON string.
+
         Parameters
         ----------
         json_str
@@ -1462,6 +1467,7 @@ def from_json(
             are globally 'applied' to all components of the TimeSeries. If a multi-row DataFrame, the number of
             rows must match the number of components of the TimeSeries (in this case, the number of columns in
             ``value_cols``). This adds control for component-specific static covariates.
+            If the JSON string already contains static covariates, this parameter will override them.
         hierarchy
             Optionally, a dictionary describing the grouping(s) of the time series. The keys are component names, and
             for a given component name `c`, the value is a list of component names that `c` "belongs" to. For instance,
@@ -1487,8 +1493,10 @@ def from_json(
             The hierarchy can be used to reconcile forecasts (so that the sums of the forecasts at
             different levels are consistent), see `hierarchical reconciliation
             <https://unit8co.github.io/darts/generated_api/darts.dataprocessing.transformers.reconciliation.html>`__.
+            If the JSON string already contains a hierarchy, this parameter will override it.
         metadata
             Optionally, a dictionary with metadata to be added to the TimeSeries.
+            If the JSON string already contains metadata, this parameter will override it.
 
         Returns
         -------
@@ -1501,16 +1509,33 @@ def from_json(
         >>> json_str = (
         >>>     '{"columns":["vals"],"index":["2020-01-01","2020-01-02","2020-01-03"],"data":[[0.0],[1.0],[2.0]]}'
         >>> )
-        >>> series = TimeSeries.from_json("data.csv")
+        >>> series = TimeSeries.from_json(json_str)
         >>> series.shape
         (3, 1, 1)
         """
+        parsed = json.loads(json_str)
+
+        static_covariates_ = parsed.pop("static_covariates", None)
+        if static_covariates_ is not None and static_covariates is None:
+            static_covariates = pd.read_json(
+                StringIO(json.dumps(static_covariates_)), orient="split"
+            )
+
+        hierarchy_ = parsed.pop("hierarchy", None)
+        if hierarchy is None:
+            hierarchy = hierarchy_
+
+        metadata_ = parsed.pop("metadata", None)
+        if metadata is None:
+            metadata = metadata_
+
+        df = pd.read_json(StringIO(json.dumps(parsed)), orient="split")
         return cls.from_dataframe(
-            df=pd.read_json(StringIO(json_str), orient="split"),
+            df=df,
             static_covariates=static_covariates,
             hierarchy=hierarchy,
             metadata=metadata,
-            copy=False,  # JSON is immutable, so no need to copy
+            copy=False,
         )
 
     @classmethod
@@ -4271,17 +4296,31 @@ def to_json(self) -> str:
 
         At the moment this function works only on deterministic time series (i.e., made of 1 sample).
 
-        Notes
-        -----
-        Static covariates are not returned in the JSON string. When using `TimeSeries.from_json()`, the static
-        covariates can be added with input argument `static_covariates`.
+        The JSON string includes the series values, time index, component names, as well as static covariates,
+        hierarchy, and metadata (if any).
 
         Returns
         -------
         str
             A JSON String representing the series
+
+        See Also
+        --------
+        TimeSeries.from_json : Create a TimeSeries from a JSON string.
         """
-        return self.to_dataframe().to_json(orient="split", date_format="iso")
+        result = json.loads(
+            self.to_dataframe().to_json(orient="split", date_format="iso")
+        )
+        if self.static_covariates is not None:
+            result["static_covariates"] = json.loads(
+                self.static_covariates.to_json(orient="split")
+            )
+        if self.hierarchy is not None:
+            result["hierarchy"] = self.hierarchy
+        if self.metadata is not None:
+            result["metadata"] = self.metadata
+
+        return json.dumps(result)
 
     def to_csv(self, *args, **kwargs):
         """Write the deterministic series to a CSV file.