rename seismic.offset to seismic.stacking_offset (#274)

* rename seismic.offset to seismic.stacking_offset

* Handle deprecated content subfields

schema/definitions/0.8.0/examples/surface_seismic_amplitude.yml

@@ -80,7 +80,7 @@ data: # The data block describes the actual data (e.g. surface). Only present in
     acquisition_start_date: 2021-04-21
     acquisition_end_date: 2021-04-30
     acquisition_reference_date: 2021-04-25
-    offset: 0-15  # near/mid/far/0-15/15-25/etc <-- Probably not to be indexed
+    stacking_offset: 0-15  # near/mid/far/0-15/15-25/etc <-- Probably not to be indexed
 
   # if stratigraphic, name must match the strat column. This is the official name of this surface.
   name: volantis_top-volantis_base

schema/definitions/0.8.0/schema/fmu_results.json

@@ -573,6 +573,12 @@
                             "examples": [
                                 1.0
                             ]
+                        },
+                        "stacking_offset": {
+                            "type": "string",
+                            "examples": [
+                                "0-15"
+                            ]
                         }
                     }
                 }

src/fmu/dataio/_definitions.py

@@ -44,7 +44,7 @@ def __post_init__(self):
         "zrange": float,
         "filter_size": float,
         "scaling_factor": float,
-        "offset": str,
+        "stacking_offset": str,
     },
     "fluid_contact": {"contact": str, "truncated": bool},
     "field_outline": {"contact": str},
@@ -59,6 +59,14 @@ def __post_init__(self):
     "timeseries": None,
 }
 
+DEPRECATED_CONTENTS = {
+    "seismic": {
+        "offset": {
+            "replaced_by": "stacking_offset",
+        }
+    }
+}
+
 # This setting will set if subkeys is required or not. If not found in list then
 # assume False.
 CONTENTS_REQUIRED = {

src/fmu/dataio/dataio.py

@@ -15,7 +15,12 @@
 import pandas as pd  # type: ignore
 
 from . import _metadata
-from ._definitions import ALLOWED_CONTENTS, ALLOWED_FMU_CONTEXTS, CONTENTS_REQUIRED
+from ._definitions import (
+    ALLOWED_CONTENTS,
+    ALLOWED_FMU_CONTEXTS,
+    CONTENTS_REQUIRED,
+    DEPRECATED_CONTENTS,
+)
 from ._utils import (
     create_symlink,
     detect_inside_rms,
@@ -184,6 +189,8 @@ def _content_validate(name, fields):
 
     logger.info("name: %s", name)
 
+    replace_deprecated = {}
+
     for key, dtype in fields.items():
         if key in valid.keys():
             wanted_type = valid[key]
@@ -192,9 +199,29 @@ def _content_validate(name, fields):
                     f"Invalid type for <{key}> with value <{dtype}>, not of "
                     f"type <{wanted_type}>"
                 )
+        elif DEPRECATED_CONTENTS.get(name, {}).get(key, None) is not None:
+            logger.debug("%s/%s is deprecated, issue warning", name, key)
+            replaced_by = DEPRECATED_CONTENTS[name][key].get("replaced_by", None)
+
+            message = f"Content {name}.{key} is deprecated. "
+
+            if replaced_by is not None:
+                message += f"Please use {replaced_by}. "
+                replace_deprecated.update({key: replaced_by})
+
+            warn(
+                message,
+                DeprecationWarning,
+            )
+
         else:
             raise ValidationError(f"Key <{key}> is not valid for <{name}>")
 
+    for key, replaced_by in replace_deprecated.items():
+        logger.debug("Replacing deprecated %s.%s with %s", name, key, replaced_by)
+        fields[replaced_by] = fields.pop(key)
+        logger.debug("Updated fields is: %s", fields)
+
     required = CONTENTS_REQUIRED.get(name, None)
     if isinstance(required, dict):
         rlist = list(required.items())

tests/test_units/test_dataio.py

@@ -127,11 +127,21 @@ def test_content_valid_dict(regsurf, globalconfig2):
     eobj = ExportData(
         config=globalconfig2,
         name="TopVolantis",
-        content={"seismic": {"attribute": "myattribute", "zrange": 12.0}},
+        content={
+            "seismic": {
+                "attribute": "myattribute",
+                "zrange": 12.0,
+                "stacking_offset": "0-15",
+            }
+        },
     )
     mymeta = eobj.generate_metadata(regsurf)
     assert mymeta["data"]["content"] == "seismic"
-    assert mymeta["data"]["seismic"] == {"attribute": "myattribute", "zrange": 12.0}
+    assert mymeta["data"]["seismic"] == {
+        "attribute": "myattribute",
+        "zrange": 12.0,
+        "stacking_offset": "0-15",
+    }
 
 
 def test_content_is_a_wrongly_formatted_dict(globalconfig2):
@@ -144,6 +154,42 @@ def test_content_is_a_wrongly_formatted_dict(globalconfig2):
         )
 
 
+def test_content_is_dict_with_wrong_types(globalconfig2):
+    """When content is a dict, it shall have right types for known keys."""
+    with pytest.raises(ValidationError):
+        ExportData(
+            config=globalconfig2,
+            name="TopVolantis",
+            content={
+                "seismic": {
+                    "stacking_offset": 123.4,  # not a string
+                }
+            },
+        )
+
+
+def test_content_deprecated_seismic_offset(regsurf, globalconfig2):
+    """Assert that usage of seismic.offset still works but give deprecation warning."""
+    with pytest.warns(DeprecationWarning, match="seismic.offset is deprecated"):
+        eobj = ExportData(
+            config=globalconfig2,
+            name="TopVolantis",
+            content={
+                "seismic": {
+                    "offset": "0-15",
+                }
+            },
+            verbosity="DEBUG",
+        )
+        mymeta = eobj.generate_metadata(regsurf)
+
+    # deprecated 'offset' replaced with 'stacking_offset'
+    assert "offset" not in mymeta["data"]["seismic"]
+    assert mymeta["data"]["seismic"] == {
+        "stacking_offset": "0-15",
+    }
+
+
 def test_global_config_from_env(globalconfig_asfile):
     """Testing getting global config from a file"""
     os.environ["FMU_GLOBAL_CONFIG"] = globalconfig_asfile