timeseries_json_to_pandas: allow timeseries as JSON dump or path

Author: soxofaan

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Harden STAC parsing of "bands"/"eo:bands" when "name" field is not present (which is technically not a required field) ([#860](https://github.com/Open-EO/openeo-python-client/issues/860))
+- `openeo.rest.conversions.timeseries_json_to_pandas`: allow timeseries to be given as a raw JSON dump or path to JSON file.
 
 ### Removed
 

openeo/rest/conversions.py

@@ -5,11 +5,14 @@
 from __future__ import annotations
 
 import typing
+from pathlib import Path
+from typing import Union
 
 import numpy as np
 import pandas
 
 from openeo.internal.warnings import deprecated
+from openeo.util import load_json_resource
 
 if typing.TYPE_CHECKING:
     # Imports for type checking only (circular import issue at runtime).
@@ -22,7 +25,9 @@ class InvalidTimeSeriesException(ValueError):
     pass
 
 
-def timeseries_json_to_pandas(timeseries: dict, index: str = "date", auto_collapse=True) -> pandas.DataFrame:
+def timeseries_json_to_pandas(
+    timeseries: Union[dict, str, Path], index: str = "date", auto_collapse=True
+) -> pandas.DataFrame:
     """
     Convert a timeseries JSON object as returned by the `aggregate_spatial` process to a pandas DataFrame object
 
@@ -32,16 +37,21 @@ def timeseries_json_to_pandas(timeseries: dict, index: str = "date", auto_collap
     When there is just a single polygon or band in play, the dataframe will be simplified
     by removing the corresponding dimension if `auto_collapse` is enabled (on by default).
 
-    :param timeseries: dictionary as returned by `aggregate_spatial`
+    :param timeseries: dictionary, JSON dump, or path to JSON file as returned by `aggregate_spatial`
     :param index: which dimension should be used for the DataFrame index: 'date' or 'polygon'
     :param auto_collapse: whether single band or single polygon cases should be simplified automatically
 
     :return: pandas DataFrame or Series
+
+    .. versionchanged:: 0.48.0
+        The `timeseries` argument to also be a JSON dump or a path to a JSON file, in addition to a dictionary.
     """
     # The input timeseries dictionary is assumed to have this structure:
     #       {dict mapping date -> [list with one item per polygon: [list with one float/None per band or empty list]]}
     # TODO is this format of `aggregate_spatial` standardized across backends? Or can we detect the structure?
-    # TODO: option to pass a path to a JSON file as input?
+
+    if not isinstance(timeseries, dict):
+        timeseries = load_json_resource(timeseries)
 
     # Some quick checks
     if len(timeseries) == 0:

tests/rest/test_conversions.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 import numpy as np
 import pandas as pd
 import pytest
@@ -26,10 +28,34 @@ def test_timeseries_json_to_pandas_basic():
         [7, 8, 9, 10, 11, 12]
     ],
         index=pd.Index([DATE1, DATE2], name="date"),
-        columns=pd.MultiIndex.from_tuples(
-            [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)],
-            names=("polygon", "band")
-        )
+        columns=pd.MultiIndex.from_tuples([(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)], names=("polygon", "band")),
+    )
+    assert_frame_equal(df, expected)
+
+
+@pytest.mark.parametrize(["path_factory"], [(str,), (Path,)])
+def test_test_timeseries_json_to_pandas_from_file(tmp_path, path_factory):
+    path = tmp_path / "timeseries.json"
+    path.write_text("""  {"2019-01-11T11:11:11Z": [[1, 2], [33, 44]]} """)
+
+    timeseries = path_factory(path)
+
+    df = timeseries_json_to_pandas(timeseries)
+    expected = pd.DataFrame(
+        data=[[1, 2, 33, 44]],
+        index=pd.Index(["2019-01-11T11:11:11Z"], name="date"),
+        columns=pd.MultiIndex.from_tuples([(0, 0), (0, 1), (1, 0), (1, 1)], names=("polygon", "band")),
+    )
+    assert_frame_equal(df, expected)
+
+
+def test_test_timeseries_json_to_pandas_from_json_dump():
+    timeseries = """  {"2019-01-11T11:11:11Z": [[1, 2], [33, 44]]} """
+    df = timeseries_json_to_pandas(timeseries)
+    expected = pd.DataFrame(
+        data=[[1, 2, 33, 44]],
+        index=pd.Index(["2019-01-11T11:11:11Z"], name="date"),
+        columns=pd.MultiIndex.from_tuples([(0, 0), (0, 1), (1, 0), (1, 1)], names=("polygon", "band")),
     )
     assert_frame_equal(df, expected)