DOC: Refine example scripts for versioned schema

.gitignore

@@ -98,7 +98,7 @@ venv.bak/
 # setuptools_scm version
 src/fmu/dataio/version.py
 # aggregated examples directory
-examples/s/d/nn/xcase/iter-0/
+examples/iter-0/
 
 
 # mypy

docs/src/examples.rst

@@ -17,7 +17,7 @@ This is a snippet of the ``global_variables.yml`` file which holds the static me
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/fmuconfig/output/global_variables.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/fmuconfig/output/global_variables.yml
       :language: yaml
 
 |
@@ -28,14 +28,14 @@ Exporting fault polygons
 Python script
 ~~~~~~~~~~~~~
 
-.. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/rms/bin/export_faultpolygons.py
+.. literalinclude:: ../../examples/realization-0/iter-0/scripts/export_polygons.py
    :language: python
 
 Press + to see generated YAML file.
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/polygons/.volantis_gp_top--faultlines.pol.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/polygons/.volantis_gp_top--faultlines.pol.yml
       :language: yaml
 
 |
@@ -46,15 +46,15 @@ Exporting average maps from grid properties
 Python script
 ~~~~~~~~~~~~~
 
-.. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/rms/bin/export_propmaps.py
+.. literalinclude:: ../../examples/realization-0/iter-0/scripts/export_propmaps.py
    :language: python
 
 
 Press + to see generated YAML file for metadata.
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/maps/.therys--average_porosity.gri.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/maps/.therys--average_porosity.gri.yml
       :language: yaml
 
 |
@@ -65,20 +65,20 @@ Exporting 3D grids with properties
 Python script
 ~~~~~~~~~~~~~
 
-.. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/any/bin/export_grid3d.py
+.. literalinclude:: ../../examples/realization-0/iter-0/scripts/export_grid3d.py
    :language: python
 
 Press + to see generated YAML files for metadata.
 
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/grids/.geogrid.roff.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/grids/.geogrid.roff.yml
       :language: yaml
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/grids/.geogrid--facies.roff.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/grids/.geogrid--facies.roff.yml
       :language: yaml
 
 |
@@ -92,12 +92,12 @@ of easy export of RMS volumetrics can be found here :ref:`example-export-volumes
 Python script
 ~~~~~~~~~~~~~
 
-.. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/any/bin/export_volumetables.py
+.. literalinclude:: ../../examples/realization-0/iter-0/scripts/export_volumetables.py
    :language: python
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/tables/.geogrid--volumes.csv.yml
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/tables/.geogrid--volumes.csv.yml
       :language: yaml
 
 |
@@ -111,45 +111,12 @@ The FaultRoom plugin for RMS produces special json files that e.g. can be viewed
 Python script
 ~~~~~~~~~~~~~
 
-.. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/rms/bin/export_faultroom_surfaces.py
+.. literalinclude:: ../../examples/realization-0/iter-0/scripts/export_faultroom_surfaces.py
    :language: python
 
 .. toggle::
 
-   .. literalinclude:: ../../examples/s/d/nn/xcase/realization-0/iter-0/share/results/maps/volantis_gp_top--faultroom_d1433e1.json
+   .. literalinclude:: ../../examples/realization-0/iter-0/share/results/maps/volantis_gp_top--faultroom_d1433e1.json
       :language: yaml
 
 |
-
-Using fmu-dataio for post-processed data
-----------------------------------------
-
-The example below shows how fmu-dataio can be used in a post-processing context, here in a
-surface aggregation example.
-
-When using ensemble-based methods for probabilistic modelling, the result is represented
-by the distribution of the realizations, not by the individual realizations themselves.
-In such a context, easy access to statistical representations of the ensemble is important.
-For surfaces, this typically includes point-wise mean, std, min/max, p10/p90 and others.
-
-Aggregations in an FMU context are usually done by standalone Python scripts, but cloud
-services are also in the making (Sumo). The example below shows how fmu-dataio can be used
-to simplify an existing aggregation service, as well as make de-centralized methods more
-robust by centralizing the definitions and handling of metadata.
-
-.. note::
-   It is common that surfaces exported from RMS or other sources have undefined areas.
-   For some surfaces, typically various thickness surfaces (e.g. HCPV thickness from RMS
-   volumetric jobs), undefined values shall be treated as zero (0.0) when included in 
-   statistical calculations. Therefore, when exporting surfaces of this type, set the 
-   `undef_is_zero` flag to `True` when exporting. This tells later consumers of the 
-   surface that they should handle `UNDEF` as zero.
-
-
-Python script
-~~~~~~~~~~~~~
-
-.. literalinclude:: ../../examples/s/d/nn/_project/aggregate_surfaces.py
-   :language: python
-
-|

examples/.gitignore

@@ -0,0 +1 @@
+/share/preprocessed

examples/README.md

@@ -0,0 +1,25 @@
+## Examples
+This folder contains scripts, config and input data to generate the examples used to demonstrate
+how `fmu-dataio` can be used for different contexts, and for different data types.
+
+In addition, you will also find examples of metadata that `fmu-dataio` produces under the
+`/share/metadata` folder. These files are used by the unit tests to test the pydantic logic.
+
+### Folders and files
+If you study the folder structure under `/examples`, you will see that there are three realizations folders:
+* Most of the logic and data exports are done by the scripts in `realization-0`.
+* The two other realizations, `realization-1` and `realization-9` are only there to export some simple
+surfaces needed in order to be able to run aggregations.
+
+The `/script` folder located at the `/examples` root contains scripts that are not related to any
+specific realizations:
+* `export_fmu_case.py`: A script that creates a new fmu case based on the current schema version.
+* `aggregate_surfaces.py`: A script that runs aggregations over the surfaces exported by the three realizations.
+
+### Running the scripts
+The bash script `run_examples.sh` runs all the python export scripts in the correct order and exports files
+and metadata to its right location so that they can be accessed by the documentation and test files. The 
+`run_examples.sh` script will mainly be run by other processes to make sure files and metadata are up to date.
+If you run it manually, make sure to run it from the root folder of the `fmu-dataio` project. Example:
+* `cd path/to/root/of/fmu-dataio/project`
+* `bash ./examples/run_examples.sh`

examples/s/d/nn/xcase/realization-0/iter-0/fmuconfig/output/global_variables.yml → examples/fmuconfig/output/global_variables.yml

@@ -71,6 +71,18 @@ stratigraphy:
   Below:
     stratigraphic: false
     name: Below
+  surface_seismic_amplitude:
+    name: surface_seismic_amplitude
+    stratigraphic: true
+    offset: 0
+    top:
+      name: volantis_gp_top
+      stratigraphic: true
+      offset: 2.0
+    base:
+      name: volantis_gp_base
+      stratigraphic: true
+      offset: 1.0
 global:
   GLOBAL_VARS_EXAMPLE: 99
   OTHER: skipped

examples/s/d/nn/xcase/realization-1/iter-0/fmuconfig/output/global_variables.yml → examples/realization-0/iter-0/fmuconfig/output/global_variables.yml

@@ -71,6 +71,18 @@ stratigraphy:
   Below:
     stratigraphic: false
     name: Below
+  surface_seismic_amplitude:
+    name: surface_seismic_amplitude
+    stratigraphic: true
+    offset: 0
+    top:
+      name: volantis_gp_top
+      stratigraphic: true
+      offset: 2.0
+    base:
+      name: volantis_gp_base
+      stratigraphic: true
+      offset: 1.0
 global:
   GLOBAL_VARS_EXAMPLE: 99
   OTHER: skipped

examples/realization-0/iter-0/output/volumes/geogrid_vol.csv

@@ -0,0 +1,22 @@
+,ZONE,REGION,FLUID,BULK_OIL,PORV_OIL,HCPV_OIL,STOIIP_OIL,ASSOCIATEDGAS_OIL,BULK_GAS,PORV_GAS,HCPV_GAS,GIIP_GAS,ASSOCIATEDOIL_GAS,BULK_TOTAL,PORV_TOTAL
+0,Valysar,WestLowland,oil,4876938.042451107,581190.4683647156,264582.9488323629,184506.9414107278,25978577.895452023,0.0,0.0,0.0,0.0,0.0,532656405.8310214,83119788.08798218
+1,Valysar,CentralSouth,oil,58259402.49817419,10654739.976043701,7779471.171012497,5425014.881680151,763842112.1403878,0.0,0.0,0.0,0.0,0.0,131036152.73035112,23636870.461090088
+2,Valysar,CentralNorth,oil,32697355.321421135,5812553.337471008,4407055.345460031,3073260.417246495,432715076.4806157,0.0,0.0,0.0,0.0,0.0,104201998.6056451,15071436.049057007
+3,Valysar,NorthHorst,oil,3729551.0330283972,453640.67844963074,228199.68520861678,140171.7932134415,27459653.421069503,23639725.74276172,2811006.095012665,1805061.0035376959,419781622.3697624,64226.58861095994,40961871.31619041,5222167.766296387
+4,Valysar,CentralRamp,oil,13278675.625716444,1960705.2695922852,1202581.7591360807,838620.491225779,118077767.92756653,0.0,0.0,0.0,0.0,0.0,13278675.625716444,1960705.2695922852
+5,Valysar,CentralHorst,oil,81106294.08357552,13203843.49725914,9886413.467727555,6894291.268356751,970716231.9162931,0.0,0.0,0.0,0.0,0.0,99791222.71840668,15746887.58328247
+6,Valysar,EastLowland,oil,447300.4585400952,62613.98971366882,22371.48907852173,15600.759775161743,2196587.0126953125,0.0,0.0,0.0,0.0,0.0,259512582.7943862,35867864.77685547
+7,Therys,WestLowland,oil,2481471.48523679,462316.99008214474,242193.6992071271,168893.7970328927,23780247.11405182,0.0,0.0,0.0,0.0,0.0,583572378.0222301,117323773.69059977
+8,Therys,CentralSouth,oil,8622547.52619993,1937075.5107873976,1198764.438779829,835958.4846980637,117702957.30660701,0.0,0.0,0.0,0.0,0.0,35293366.818518646,7481335.479992241
+9,Therys,CentralNorth,oil,19410309.683232084,3966510.444923401,2348694.981575855,1637862.6439988734,230611065.7746482,0.0,0.0,0.0,0.0,0.0,85932343.21466546,15522664.101458132
+10,Therys,NorthHorst,oil,6823659.20864031,1007703.5360636115,400838.25561304577,246215.1389733022,48233544.23920667,18073352.811639804,2946629.4134296775,1885641.0872489214,438521176.3771229,67093.74034424196,41548106.4639971,6631236.629718244
+11,Therys,CentralRamp,oil,6986106.91343112,1559392.3712798655,1162528.7107956968,810689.4947146513,114145083.41399097,0.0,0.0,0.0,0.0,0.0,6986106.91343112,1559392.3712798655
+12,Therys,CentralHorst,oil,28324932.76265244,7511635.677255213,5718945.423280798,3988107.073664233,561525489.4145021,0.0,0.0,0.0,0.0,0.0,46559648.59471566,11082579.058495943
+13,Therys,EastLowland,oil,1.1804434920011317,0.4017864614725113,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,97234205.36140853,20122123.73043558
+14,Volon,WestLowland,oil,314203.72062076884,56738.82876777649,36004.46552276611,25107.716999053955,3535166.626220703,0.0,0.0,0.0,0.0,0.0,456452803.8185824,83058507.18912272
+15,Volon,CentralSouth,oil,25503908.61473126,4569845.064310074,3372058.6200942993,2351505.36328125,331091962.732666,0.0,0.0,0.0,0.0,0.0,211084477.98194948,39658805.76940918
+16,Volon,CentralNorth,oil,5095024.441235964,631244.6275720596,284197.46631622314,198185.12700653076,27904466.495117188,0.0,0.0,0.0,0.0,0.0,40937928.04154923,5948331.291053772
+17,Volon,NorthHorst,oil,4758901.09053987,799221.6588745117,555436.0459060669,341176.92469501495,66836557.46020508,3303432.2018888853,630713.8162069321,544865.7386512756,126712960.38476562,19387.083025455475,15486028.093797322,2809892.851211548
+18,Volon,CentralRamp,oil,10998196.14907306,1912876.138250351,1396981.229751587,974184.9782562256,137165248.09765625,0.0,0.0,0.0,0.0,0.0,13550670.68040854,2428892.057861328
+19,Volon,CentralHorst,oil,79681545.04055436,14375965.719596863,11182299.305984497,7797977.370236397,1097955237.7382812,0.0,0.0,0.0,0.0,0.0,110619757.785571,19760267.584091187
+20,Volon,EastLowland,oil,389.20061489841703,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,194409495.59477484,34434411.80543518

examples/realization-0/iter-0/output/volumes/simgrid_vol.csv

@@ -0,0 +1,22 @@
+,ZONE,REGION,FLUID,BULK_OIL,PORV_OIL,HCPV_OIL,STOIIP_OIL,ASSOCIATEDGAS_OIL,BULK_GAS,PORV_GAS,HCPV_GAS,GIIP_GAS,ASSOCIATEDOIL_GAS,BULK_TOTAL,PORV_TOTAL
+0,Valysar,WestLowland,oil,4863148.691947548,581953.6194000244,242983.30458184704,169444.42844098806,23857776.070989132,0.0,0.0,0.0,0.0,0.0,532656961.4001149,83116573.53366089
+1,Valysar,CentralSouth,oil,58246749.73665969,10642870.257009506,7682283.247654736,5357240.876057565,754299531.2526016,0.0,0.0,0.0,0.0,0.0,131036985.30226907,23637013.020599365
+2,Valysar,CentralNorth,oil,32716307.184978276,5815197.184371948,4345047.784405708,3030019.4432046413,426626747.30914307,0.0,0.0,0.0,0.0,0.0,104201851.02682042,15071388.356140137
+3,Valysar,NorthHorst,oil,3731447.1236388907,446469.7942085266,198098.90879774094,121682.37313556671,23837576.166778564,23636333.19079261,2818479.5756759644,1812019.7860803604,421399943.1043091,64474.191660150886,40961520.97868073,5222093.303344727
+4,Valysar,CentralRamp,oil,13279498.078432752,1960806.5362243652,1202636.8689098358,838658.9225883484,118083178.9296875,0.0,0.0,0.0,0.0,0.0,13279498.078432752,1960806.5362243652
+5,Valysar,CentralHorst,oil,81104230.43657318,13205938.919624329,9858165.994581461,6874592.889423132,967942700.284729,0.0,0.0,0.0,0.0,0.0,99789472.97854897,15746591.911056519
+6,Valysar,EastLowland,oil,443565.6536892501,62647.9548034668,16611.719053268433,11584.183688163757,1631053.1057128906,0.0,0.0,0.0,0.0,0.0,259515030.28451037,35868304.27471924
+7,Therys,WestLowland,oil,2478082.6591502046,460018.07080841064,222467.2900876403,155137.5829963088,21843372.45514679,0.0,0.0,0.0,0.0,0.0,583573382.6311626,117292863.11933899
+8,Therys,CentralSouth,oil,8610005.1663712,1924022.7452037334,1154945.7453138828,805401.5135338902,113400535.80075073,0.0,0.0,0.0,0.0,0.0,35294264.283889204,7467189.483840942
+9,Therys,CentralNorth,oil,19394437.26709871,3964274.0973472595,2294938.6829174757,1600375.6897594035,225332902.4863472,0.0,0.0,0.0,0.0,0.0,85931285.72998607,15516414.203811646
+10,Therys,NorthHorst,oil,6826337.936624451,1004030.0196914673,384070.4337749481,235915.49477458,46215843.907562256,18072691.419149697,2949050.390350342,1881118.622177124,437469439.33587646,66932.8246640414,41546724.22354915,6628302.395599365
+11,Therys,CentralRamp,oil,6986770.598701181,1558357.5761108398,1162414.0995316505,810609.571448803,114133829.99664307,0.0,0.0,0.0,0.0,0.0,6986770.598701181,1558357.5761108398
+12,Therys,CentralHorst,oil,28319277.439605713,7505118.981826782,5693770.748996735,3970551.501933098,559053663.7792969,0.0,0.0,0.0,0.0,0.0,46567683.23932478,11079013.95741272
+13,Therys,EastLowland,gas,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,97228715.38685408,20106577.598892212
+14,Volon,WestLowland,oil,309924.2683946667,56263.94061279297,28846.4541015625,20116.076942443848,2832343.7216796875,0.0,0.0,0.0,0.0,0.0,456453792.9092857,83041031.89674377
+15,Volon,CentralSouth,oil,25498154.661032636,4588895.460144043,3135693.2482852936,2186675.9573278427,307883981.1907959,0.0,0.0,0.0,0.0,0.0,211086356.06057668,39659137.904785156
+16,Volon,CentralNorth,oil,5093636.405269821,634201.2610015869,271256.4369239807,189160.69971466064,26633827.19091797,0.0,0.0,0.0,0.0,0.0,40938736.30922581,5948438.199584961
+17,Volon,NorthHorst,oil,4749582.529529197,802134.2102203369,539439.3651618958,331350.95287799835,64911649.7722168,3307898.4007633706,630107.2222137451,542490.1662139893,126160502.01171875,19302.556921482086,15486130.132892353,2809893.6099853516
+18,Volon,CentralRamp,oil,11002841.070472872,1915892.3193817139,1367002.4863967896,953279.3022003174,134221728.70410156,0.0,0.0,0.0,0.0,0.0,13549592.495815616,2428686.719482422
+19,Volon,CentralHorst,oil,79683116.145247,14392992.721878052,11118249.318931103,7753312.100895286,1091666367.49292,0.0,0.0,0.0,0.0,0.0,110619921.94782586,19760301.35534668
+20,Volon,EastLowland,gas,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,194408791.05640477,34434323.932006836

examples/s/d/nn/xcase/realization-0/iter-0/rms/bin/export_faultroom_surfaces.py → examples/realization-0/iter-0/scripts/export_faultroom_surfaces.py

@@ -9,13 +9,13 @@
 logger = logging.getLogger(__name__)
 logger.setLevel(logging.WARNING)
 
-CFG = utils.yaml_load("../../fmuconfig/output/global_variables.yml")
+CFG = utils.yaml_load("../fmuconfig/output/global_variables.yml")
 
 # if running outside RMS using files that are stored e.g. on rms/output
 FAULTROOM_FILE = Path("../output/faultroom/some_faultroom.json")
 
 
-def export_faultroom_surface():
+def main():
     """Export faultroom data, json files made by FaultRoom plugin in RMS"""
 
     # read file and return a FaultRoomSurface instance
@@ -33,8 +33,11 @@ def export_faultroom_surface():
         tagname=faultroom_object.tagname,
     )
 
-    ed.export(faultroom_object)
+    fname = ed.export(faultroom_object)
+    print(f"Exported to file {fname}")
 
 
 if __name__ == "__main__":
-    export_faultroom_surface()
+    print("\nExporting faultroom surface maps and metadata...")
+    main()
+    print("Done exporting faultroom surface maps and metadta.")

examples/s/d/nn/xcase/realization-0/iter-0/any/bin/export_grid3d.py → examples/realization-0/iter-0/scripts/export_grid3d.py

@@ -8,10 +8,10 @@
 from fmu import dataio
 from fmu.config import utilities as ut
 
-logging.basicConfig(level=logging.DEBUG)
+logging.basicConfig(level=logging.WARNING)
 logger = logging.getLogger(__name__)
 
-CFG = ut.yaml_load("../../fmuconfig/output/global_variables.yml")
+CFG = ut.yaml_load("../fmuconfig/output/global_variables.yml")
 
 FOLDER = pathlib.Path("../output/grids")
 GFILE = "gg"
@@ -39,7 +39,7 @@ def export_geogrid_geometry():
     )
 
     out = ed.export(grd)
-    print(f"Stored grid as {out}")
+    print(f"Exported geogrid geometry to file {out}")
     return out
 
 
@@ -48,7 +48,6 @@ def export_geogrid_parameters(outgrid):
 
     props = PROPS_SEISMIC + PROPS_OTHER
 
-    print("Write grid properties...")
     for propname in props:
         filename = (FOLDER / (GFILE + "_" + propname)).with_suffix(".roff")
         prop = xtgeo.gridproperty_from_file(filename)
@@ -67,10 +66,11 @@ def export_geogrid_parameters(outgrid):
         )
 
         out = ed.export(prop)
-        print(f"Stored {propname} as {out}")
+        print(f"Exported {propname} property geogrid to file {out}")
 
 
 if __name__ == "__main__":
+    print("\nExporting geogrids and metadata...")
     outgrid = export_geogrid_geometry()
     export_geogrid_parameters(outgrid)
-    print("Done.")
+    print("Done exporting geogrids and metadata.")