Merge branch 'main' into 249-filter-on-content

docs/explorer.rst

@@ -34,8 +34,8 @@ Api Reference
 - `API reference <apiref/fmu.sumo.explorer.html>`_
 
 .. warning::
-    OpenVDS does not publish builds for MacOS. You can still use the Explorer without OpenVDS,
-    but some Cube methods will not work.
+    OpenVDS does not publish builds for MacOS nor for Python version 3.12. You can still use the 
+    Explorer without OpenVDS, but some Cube methods will not work.
 
 Usage and examples
 ------------------
@@ -250,7 +250,7 @@ The `SurfaceCollection.filter` method takes the following parameters:
 * uuid
 * name 
 * content 
-* tagname 
+* dataformat
 * iteration 
 * realization 
 * aggregation
@@ -286,8 +286,8 @@ Example: get aggregated surfaces
 We can get list of filter values for the following properties:
 
 * names
-* tagnames 
 * contents 
+* dataformats
 * iterations 
 * realizations
 * aggregations 
@@ -310,10 +310,11 @@ Once we have a `Surface` object we can get surface metadata using properties:
 
     surface = case.surfaces[0]
 
-    print(surfaces.uuid)
-    print(surfaces.name)
     print(surface.content)
-    print(surfaces.tagname)
+    print(surface.uuid)
+    print(surface.name)
+    print(surface.tagname)
+    print(surface.dataformat)
     print(surface.stratigraphic)
     print(surface.vertical_domain)
 
@@ -507,4 +508,4 @@ The `SurfaceCollection` class can be used to do on-demand surface aggregations.
     p10.quickplot()
 
 In this example we perform aggregations on all realized instance of the surface `Valysar Fm. (FACIES_Fraction_Channel)` in iteration 0.
-The aggregation methods return `xtgeo.RegularSurface` objects.
+The aggregation methods return `xtgeo.RegularSurface` objects.

examples/explorer.ipynb

@@ -124,6 +124,9 @@
     "# Filter on name\n",
     "surfs = surfs.filter(name=\"Valysar Fm.\")\n",
     "\n",
+    "# Filter on format\n",
+    "surfs = surfs.filter(dataformat=\"irap_binary\")\n",
+    "\n",
     "# Get available tagnames\n",
     "print(\"Tagnames:\", surfs.tagnames)\n",
     "\n",
@@ -133,11 +136,11 @@
     "# Iterate over results\n",
     "print(\"\\nResults:\", len(surfs))\n",
     "\n",
-    "# Sort by realization\n",
-    "sorted_surfs = sorted(surfs, key=lambda x:x.realization)\n",
-    "\n",
-    "for surf in sorted_surfs:\n",
-    "    print(f\"\\n Realization {surf.realization}: {surf.name} ({surf.content}) ({surf.uuid})\")\n",
+    "for surf in surfs:\n",
+    "    print(\"\\n\")\n",
+    "    print(\"ID:\", surf.uuid)\n",
+    "    print(\"Format:\", surf.dataformat)\n",
+    "    print(\"Realization:\", surf.realization)\n",
     "\n",
     "# Select one surface instance\n",
     "surf = surfs[0]\n",
@@ -147,6 +150,7 @@
     "print(\"Name:\", surf.name)\n",
     "print(\"Content:\", surf.content)\n",
     "print(\"Tagname:\", surf.tagname)\n",
+    "print(\"Format:\", surf.dataformat)\n",
     "print(\"Iteration:\", surf.iteration)\n",
     "print(\"Realization:\", surf.realization)\n",
     "print(\"vertical domain:\", surf.vertical_domain)\n",
@@ -321,7 +325,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.18"
+   "version": "3.11.4"
   },
   "orig_nbformat": 4,
   "vscode": {

src/fmu/sumo/explorer/objects/_child.py

@@ -71,6 +71,12 @@ def stage(self) -> str:
 
     @property
     def format(self) -> str:
+        """Object file format"""
+        # (Legacy) alias for `dataformat`. Deprecate at some point?
+        return self.dataformat
+
+    @property
+    def dataformat(self) -> str:
         """Object file format"""
         return self._get_property(["data", "format"])
 

src/fmu/sumo/explorer/objects/_child_collection.py

@@ -1,4 +1,5 @@
 """Module containing class for collection of children"""
+
 from typing import List, Dict, Union
 from sumo.wrapper import SumoClient
 from fmu.sumo.explorer.objects._document_collection import DocumentCollection
@@ -7,10 +8,7 @@
 
 _CHILD_FIELDS = {
     "include": [],
-    "exclude": [
-        "data.spec.columns",
-        "fmu.realization.parameters"
-    ]
+    "exclude": ["data.spec.columns", "fmu.realization.parameters"],
 }
 
 
@@ -48,6 +46,16 @@ async def tagnames_async(self) -> List[str]:
         """List of unqiue object tagnames"""
         return await self._get_field_values_async("data.tagname.keyword")
 
+    @property
+    def dataformats(self) -> List[str]:
+        """List of unique data.format values"""
+        return self._get_field_values("data.format.keyword")
+
+    @property
+    async def dataformats_async(self) -> List[str]:
+        """List of unique data.format values"""
+        return await self._get_field_values_async("data.format.keyword")
+
     @property
     def iterations(self) -> List[int]:
         """List of unique object iteration names"""
@@ -76,7 +84,9 @@ def aggregations(self) -> List[str]:
     @property
     async def aggregations_async(self) -> List[str]:
         """List of unique object aggregation operations"""
-        return await self._get_field_values_async("fmu.aggregation.operation.keyword")
+        return await self._get_field_values_async(
+            "fmu.aggregation.operation.keyword"
+        )
 
     @property
     def stages(self) -> List[str]:
@@ -107,7 +117,7 @@ def vertical_domain(self) -> List[str]:
     async def vertical_domain_async(self) -> List[str]:
         """List of unqiue object vertical domain"""
         return await self._get_field_values_async("data.vertical_domain")
-   
+
     @property
     def contents(self) -> List[str]:
         """List of unique contents"""
@@ -134,6 +144,7 @@ def _add_filter(
         self,
         name: Union[str, List[str], bool] = None,
         tagname: Union[str, List[str], bool] = None,
+        dataformat: Union[str, List[str], bool] = None,
         iteration: Union[str, List[str], bool] = None,
         realization: Union[int, List[int], bool] = None,
         aggregation: Union[str, List[str], bool] = None,
@@ -145,22 +156,23 @@ def _add_filter(
         vertical_domain: Union[str, List[str], bool] = None,
         content: Union[str, List[str], bool] = None,
         is_observation: bool = None,
-        is_prediction: bool = None
+        is_prediction: bool = None,
     ):
         must = []
         must_not = []
 
         prop_map = {
             "data.name.keyword": name,
             "data.tagname.keyword": tagname,
+            "data.format": dataformat,
             "fmu.iteration.name.keyword": iteration,
             "fmu.realization.id": realization,
             "fmu.aggregation.operation.keyword": aggregation,
             "fmu.context.stage.keyword": stage,
             "data.spec.columns.keyword": column,
             "_id": uuid,
             "data.vertical_domain.keyword": vertical_domain,
-            "data.content.keyword": content
+            "data.content.keyword": content,
         }
 
         for prop, value in prop_map.items():
@@ -177,7 +189,7 @@ def _add_filter(
         bool_prop_map = {
             "data.stratigraphic": stratigraphic,
             "data.is_observation": is_observation,
-            "data.is_prediction": is_prediction
+            "data.is_prediction": is_prediction,
         }
         for prop, value in bool_prop_map.items():
             if value is not None:

src/fmu/sumo/explorer/objects/surface_collection.py

@@ -166,6 +166,7 @@ def filter(
         self,
         name: Union[str, List[str], bool] = None,
         tagname: Union[str, List[str], bool] = None,
+        dataformat: Union[str, List[str], bool] = None,
         stratigraphic: Union[str, List[str], bool] = None,
         vertical_domain: Union[str, List[str], bool] = None,
         iteration: Union[str, List[str], bool] = None,
@@ -185,6 +186,7 @@ def filter(
         Args:
             name (Union[str, List[str], bool]): surface name
             tagname (Union[str, List[str], bool]): surface tagname
+            dataformat (Union[str, List[str], bool]): surface data format
             iteration (Union[int, List[int], bool]): iteration id
             realization Union[int, List[int], bool]: realization id
             aggregation (Union[str, List[str], bool]): aggregation operation
@@ -236,6 +238,7 @@ def filter(
         query = super()._add_filter(
             name=name,
             tagname=tagname,
+            dataformat=dataformat,
             iteration=iteration,
             realization=realization,
             aggregation=aggregation,

tests/test_explorer.py

@@ -195,7 +195,7 @@ def test_get_cases_combinations(explorer: Explorer):
 
 
 def test_case_surfaces_type(test_case: Case):
-    """Test that Case.surfaces property is of rype SurfaceCollection"""
+    """Test that Case.surfaces property is of type SurfaceCollection"""
     assert isinstance(test_case.surfaces, SurfaceCollection)
 
 
@@ -228,6 +228,9 @@ def test_case_surfaces_filter(test_case: Case):
         assert surf.iteration == "iter-0"
 
     # filter on name
+    non_valid_name_surfs = real_surfs.filter(name="___not_valid")
+    assert len(non_valid_name_surfs) == 0
+
     real_surfs = real_surfs.filter(name="Valysar Fm.")
     assert len(real_surfs) == 56
 
@@ -243,6 +246,9 @@ def test_case_surfaces_filter(test_case: Case):
     assert len(real_surfs) == 56
 
     # filter on tagname
+    non_valid_tagname_surfs = real_surfs.filter(tagname="___not_valid")
+    assert len(non_valid_tagname_surfs) == 0
+
     real_surfs = real_surfs.filter(tagname="FACIES_Fraction_Channel")
     assert len(real_surfs) == 4
 
@@ -251,6 +257,13 @@ def test_case_surfaces_filter(test_case: Case):
         assert surf.name == "Valysar Fm."
         assert surf.tagname == "FACIES_Fraction_Channel"
 
+    # filter on data format
+    non_valid_format_surfs = real_surfs.filter(dataformat="___not_valid")
+    assert len(non_valid_format_surfs) == 0
+
+    real_surfs = real_surfs.filter(dataformat="irap_binary")
+    assert len(real_surfs) == 4
+
     # filter on realization
     real_surfs = real_surfs.filter(realization=0)
     assert len(real_surfs) == 1