Extend WebAPI to derive time series and statistics for datasets with multiple non-spatial dimensions

CHANGES.md

@@ -5,6 +5,11 @@
   that comes with, e.g., several bug fixes including issues with the time series legend,
   the zoom information box, persisted states, and the progress bar, as well as updated 
   dependencies such as `chartlets ^0.2.0`.
+* WebAPI now supports statistics and time series for dataset variables with
+  additional non-spatial dimensions beyond `time`, `lat`, and `lon` (e.g. `depth`).
+  Dimension values can be passed as query parameters; if omitted, a value is selected
+  automatically. As part of this, `xcube.core.tile.get_non_spatial_labels` has been
+  made a public function. (#1213)
 
 ### Fixes
 * Adapted to xarray version 2026.04.0 (#1211)

test/webapi/datasets/test_controllers.py

@@ -42,7 +42,7 @@ def assertDatasetsOk(self, response: Any, expected_count: Optional[int] = None):
 class DatasetsControllerTest(DatasetsControllerTestBase):
     def test_datasets(self):
         response = get_datasets(get_datasets_ctx())
-        datasets = self.assertDatasetsOk(response, expected_count=2)
+        datasets = self.assertDatasetsOk(response, expected_count=3)
         for dataset in datasets:
             self.assertIsInstance(dataset, dict)
             self.assertIn("id", dataset)
@@ -55,7 +55,7 @@ def test_dataset_with_details(self):
         response = get_datasets(
             get_datasets_ctx(), details=True, base_url="http://test"
         )
-        datasets = self.assertDatasetsOk(response, expected_count=2)
+        datasets = self.assertDatasetsOk(response, expected_count=3)
 
         demo_dataset = None
         demo_1w_dataset = None
@@ -97,7 +97,7 @@ def test_dataset_with_point(self):
         response = get_datasets(
             get_datasets_ctx(), point=(1.7, 51.2), base_url="http://test"
         )
-        datasets = self.assertDatasetsOk(response, expected_count=2)
+        datasets = self.assertDatasetsOk(response, expected_count=3)
         dataset = datasets[0]
         self.assertIsInstance(dataset, dict)
         self.assertIn("id", dataset)
@@ -114,7 +114,7 @@ def test_dataset_with_point_and_details(self):
         response = get_datasets(
             get_datasets_ctx(), point=(1.7, 51.2), details=True, base_url="http://test"
         )
-        datasets = self.assertDatasetsOk(response, expected_count=2)
+        datasets = self.assertDatasetsOk(response, expected_count=3)
         dataset = datasets[0]
         self.assertIsInstance(dataset, dict)
         self.assertIn("id", dataset)

test/webapi/ows/stac/test_controllers.py

@@ -136,7 +136,7 @@
             "title": f'Feature for the dataset "{dsid}"',
             "type": "application/geo+json",
         }
-        for dsid in ["demo", "demo-1w"]
+        for dsid in ["demo", "demo-1w", "demo-multidimensional"]
     ],
     "providers": [],
     "stac_version": STAC_VERSION,
@@ -234,7 +234,7 @@ def test_get_datasets_collection_items(self):
 
         features = result["features"]
         self.assertIsInstance(features, list)
-        self.assertEqual(2, len(features))
+        self.assertEqual(3, len(features))
 
         for feature in features:
             self.assertIsInstance(feature, dict)
@@ -245,7 +245,7 @@ def test_get_datasets_collection_items(self):
             self.assertIsInstance(feature.get("geometry"), dict)
             self.assertIsInstance(feature.get("assets"), dict)
             self.assertIsInstance(feature.get("id"), str)
-            self.assertIn(feature["id"], {"demo", "demo-1w"})
+            self.assertIn(feature["id"], {"demo", "demo-1w","demo-multidimensional"})
             # TODO (forman): add more assertions
             # import pprint
             # pprint.pprint(feature)
@@ -300,7 +300,7 @@ def test_get_collections(self):
         )
         self.assertEqual(EXPECTED_DATASETS_COLLECTION, result["collections"][0])
         self.assertEqual(
-            ["datacubes", "demo", "demo-1w"],
+            ["datacubes", "demo", "demo-1w", "demo-multidimensional"],
             [collection["id"] for collection in result["collections"]],
         )
 

test/webapi/ows/wmts/res/WMTSCapabilities-CRS84.xml

@@ -493,6 +493,45 @@
         <Value>2017-02-05T00:00:00.000000000</Value>
       </Dimension>
     </Layer>
+    <Layer>
+      <ows:Identifier>demo-multidimensional.conc_chl</ows:Identifier>
+      <ows:Title>demo-multidimensional/Chlorophyll concentration</ows:Title>
+      <ows:Abstract/>
+      <ows:WGS84BoundingBox>
+        <ows:LowerCorner>0 50</ows:LowerCorner>
+        <ows:UpperCorner>5 52.5</ows:UpperCorner>
+      </ows:WGS84BoundingBox>
+      <Style isDefault="true">
+        <ows:Identifier>Default</ows:Identifier>
+      </Style>
+      <Format>image/png</Format>
+      <TileMatrixSetLink>
+        <TileMatrixSet>WorldCRS84Quad</TileMatrixSet>
+      </TileMatrixSetLink>
+      <ResourceURL format="image/png" resourceType="tile" template="http://bibo/wmts/1.0.0/tile/demo-multidimensional/conc_chl/WorldCRS84Quad/{TileMatrix}/{TileRow}/{TileCol}.png"/>
+      <Dimension>
+        <ows:Identifier>depth</ows:Identifier>
+        <ows:Title>depth</ows:Title>
+        <ows:UOM/>
+        <Default>0</Default>
+        <Current>false</Current>
+        <Value>0.0</Value>
+        <Value>10.0</Value>
+        <Value>20.0</Value>
+      </Dimension>
+      <Dimension>
+        <ows:Identifier>time</ows:Identifier>
+        <ows:Title>time</ows:Title>
+        <ows:UOM>ISO8601</ows:UOM>
+        <Default>current</Default>
+        <Current>true</Current>
+        <Value>2017-01-16T10:09:21.834255872</Value>
+        <Value>2017-01-25T09:35:51.060063488</Value>
+        <Value>2017-01-26T10:50:16.686192896</Value>
+        <Value>2017-01-28T09:58:11.350386176</Value>
+        <Value>2017-01-30T10:46:33.836892416</Value>
+      </Dimension>
+    </Layer>
     <TileMatrixSet>
       <ows:Identifier>WorldCRS84Quad</ows:Identifier>
       <ows:Title>CRS84 for the World</ows:Title>
@@ -632,6 +671,17 @@
         <LayerRef>demo-1w.quality_flags_stdev</LayerRef>
       </Theme>
     </Theme>
+    <Theme>
+      <ows:Identifier>demo-multidimensional</ows:Identifier>
+      <ows:Title>Demonstration Multidimensional Cube</ows:Title>
+      <ows:Abstract/>
+      <Theme>
+        <ows:Identifier>demo-multidimensional.conc_chl</ows:Identifier>
+        <ows:Title>demo-multidimensional/Chlorophyll concentration</ows:Title>
+        <ows:Abstract/>
+        <LayerRef>demo-multidimensional.conc_chl</LayerRef>
+      </Theme>
+    </Theme>
   </Themes>
   <ServiceMetadataURL xlink:href="http://bibo/wmts/1.0.0/WorldCRS84Quad/WMTSCapabilities.xml"/>
 </Capabilities>

test/webapi/ows/wmts/res/WMTSCapabilities-OSM.xml

@@ -493,6 +493,45 @@
         <Value>2017-02-05T00:00:00.000000000</Value>
       </Dimension>
     </Layer>
+    <Layer>
+      <ows:Identifier>demo-multidimensional.conc_chl</ows:Identifier>
+      <ows:Title>demo-multidimensional/Chlorophyll concentration</ows:Title>
+      <ows:Abstract/>
+      <ows:WGS84BoundingBox>
+        <ows:LowerCorner>0 50</ows:LowerCorner>
+        <ows:UpperCorner>5 52.5</ows:UpperCorner>
+      </ows:WGS84BoundingBox>
+      <Style isDefault="true">
+        <ows:Identifier>Default</ows:Identifier>
+      </Style>
+      <Format>image/png</Format>
+      <TileMatrixSetLink>
+        <TileMatrixSet>WorldWebMercatorQuad</TileMatrixSet>
+      </TileMatrixSetLink>
+      <ResourceURL format="image/png" resourceType="tile" template="http://bibo/wmts/1.0.0/tile/demo-multidimensional/conc_chl/WorldWebMercatorQuad/{TileMatrix}/{TileRow}/{TileCol}.png"/>
+      <Dimension>
+        <ows:Identifier>depth</ows:Identifier>
+        <ows:Title>depth</ows:Title>
+        <ows:UOM/>
+        <Default>0</Default>
+        <Current>false</Current>
+        <Value>0.0</Value>
+        <Value>10.0</Value>
+        <Value>20.0</Value>
+      </Dimension>
+      <Dimension>
+        <ows:Identifier>time</ows:Identifier>
+        <ows:Title>time</ows:Title>
+        <ows:UOM>ISO8601</ows:UOM>
+        <Default>current</Default>
+        <Current>true</Current>
+        <Value>2017-01-16T10:09:21.834255872</Value>
+        <Value>2017-01-25T09:35:51.060063488</Value>
+        <Value>2017-01-26T10:50:16.686192896</Value>
+        <Value>2017-01-28T09:58:11.350386176</Value>
+        <Value>2017-01-30T10:46:33.836892416</Value>
+      </Dimension>
+    </Layer>
     <TileMatrixSet>
       <ows:Identifier>WorldWebMercatorQuad</ows:Identifier>
       <ows:Title>Google Maps Compatible for the World</ows:Title>
@@ -632,6 +671,17 @@
         <LayerRef>demo-1w.quality_flags_stdev</LayerRef>
       </Theme>
     </Theme>
+    <Theme>
+      <ows:Identifier>demo-multidimensional</ows:Identifier>
+      <ows:Title>Demonstration Multidimensional Cube</ows:Title>
+      <ows:Abstract/>
+      <Theme>
+        <ows:Identifier>demo-multidimensional.conc_chl</ows:Identifier>
+        <ows:Title>demo-multidimensional/Chlorophyll concentration</ows:Title>
+        <ows:Abstract/>
+        <LayerRef>demo-multidimensional.conc_chl</LayerRef>
+      </Theme>
+    </Theme>
   </Themes>
   <ServiceMetadataURL xlink:href="http://bibo/wmts/1.0.0/WorldWebMercatorQuad/WMTSCapabilities.xml"/>
 </Capabilities>

test/webapi/res/config-stats.yml

@@ -44,6 +44,22 @@ Datasets:
     Path: ../../../examples/serve/demo/sample-cog.tif
     Style: tif_style
 
+  - Identifier: demo-multidimensional
+    Title: Demonstration Multidimensional Cube
+    GroupTitle: Multidimensional Demo
+    Tags: ["demo", "computed"]
+    FileSystem: memory
+    Path: script.py
+    Variables:
+      - "conc_chl"
+    Function: simulate_multidimensional_dataset
+    InputDatasets: ["demo"]
+    InputParameters:
+      variables: ["conc_chl"]
+      depths: [0.0, 10.0, 20.0]
+      factor: 0.2
+    Style: default
+
 PlaceGroups:
   - Identifier: inside-cube
     Title: Points inside the cube

test/webapi/res/config.yml

@@ -37,6 +37,22 @@ Datasets:
       incl_stdev: True
     Style: default
 
+  - Identifier: demo-multidimensional
+    Title: Demonstration Multidimensional Cube
+    GroupTitle: Multidimensional Demo
+    Tags: ["demo", "computed"]
+    FileSystem: memory
+    Path: script.py
+    Variables:
+      - "conc_chl"
+    Function: simulate_multidimensional_dataset
+    InputDatasets: ["demo"]
+    InputParameters:
+      variables: ["conc_chl"]
+      depths: [0.0, 10.0, 20.0]
+      factor: 0.2
+    Style: default
+
 PlaceGroups:
   - Identifier: inside-cube
     Title: Points inside the cube

test/webapi/res/script.py

@@ -2,6 +2,7 @@
 # Permissions are hereby granted under the terms of the MIT License:
 # https://opensource.org/licenses/MIT.
 
+import pandas as pd
 import numpy as np
 import xarray as xr
 
@@ -62,3 +63,31 @@ def broken_ml_dataset_factory_1():
 def broken_ml_dataset_factory_2(ml_dataset: MultiLevelDataset):
     """Example for a custom, broken MultiLevelDataset class."""
     return xr.Dataset()
+
+
+def simulate_multidimensional_dataset(ds, variables, depths, factor):
+    dim_name = "depth"
+
+    depth_coord = xr.DataArray(depths, dims=(dim_name,), coords={dim_name: depths})
+    depth_factors = xr.DataArray(
+        [factor**i for i in range(len(depths))],
+        dims=(dim_name,),
+        coords={dim_name: depths},
+    )
+
+    data_vars = {}
+
+    for name in variables:
+        data = ds[name]
+
+        if dim_name in data.dims:
+            data_vars[name] = data
+            continue
+
+        data_expanded = data.expand_dims({dim_name: depths})
+        data_scaled = data_expanded * depth_factors
+
+        data_scaled.attrs.update(data.attrs)
+        data_vars[name] = data_scaled
+
+    return xr.Dataset(data_vars, coords={dim_name: depth_coord})