diff --git a/docs/examples.rst b/docs/examples.rst index 1ed942bd5..8c72b389d 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -102,7 +102,7 @@ Python script Using fmu-dataio for post-processed data ---------------------------------------- -The example below show how fmu-dataio can be used in a post-processing context, here in a +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 @@ -110,8 +110,8 @@ by the distribution of the realizations, not by the individual realizations them 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 is usually done by standalone Python scripts, but cloud -services are also in the making (Sumo). The example below show how fmu-dataio can be used +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. diff --git a/docs/overview.rst b/docs/overview.rst index 21ed229d0..a848d1bf4 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -13,8 +13,8 @@ Static and object-specific metadata Metadata are in general "data about the data". For instance a pure surface export file (e.g. irap binary) will have information about data itself (like -values in the map, and bounding box) but the file have no idea of which FMU run it -belongs to, or which field it comes from or what horizon is represents. +values in the map, and bounding box) but the file has no idea of which FMU run it +belongs to, or which field it comes from or what horizon it represents. Some metadata contents are *static for the model*, meaning that they will be the same for all runs of a specific model setup. Examples are masterdata relations @@ -27,7 +27,7 @@ Other metadata are object-specific, i.e. they will vary per item which is export instance, content metadata are object-specific as some surfaces are in depth domain, some in time and other represents e.g. an average property. -Basicly it works like this in a FMU run: +Basically it works like this in a FMU run: * *Metadata static for the model* comes from the fmu-config YAML file. * *Metadata static for the case* comes from ERT. @@ -41,9 +41,9 @@ The data model used for FMU results is a partly denormalized data model, meaning static data will be repeated across many data objects. Example: Each exported data object contains basic information about the FMU case it belongs to, such as a unique ID for this case, its name, the user that made it, which model template was used, etc. This information -if stored in *every* exported .yml file. This may seem counter-intuitive and differs +is stored in *every* exported .yml file. This may seem counter-intuitive and differs from a relational database (where this information would typically be stored once, and -refered to when needed). +referred to when needed). The FMU results data model is further documented `here <./datamodel.html>`__ @@ -51,4 +51,4 @@ Getting started =============== To get started, your FMU workflow must be retrofitted with a few improvements further -described `here <./preparations.html>`__ \ No newline at end of file +described `here <./preparations.html>`__ diff --git a/docs/preparations.rst b/docs/preparations.rst index 7e7bf80b1..413901ad2 100644 --- a/docs/preparations.rst +++ b/docs/preparations.rst @@ -5,9 +5,10 @@ In order to start using fmu-dataio and produce valid metadata for FMU output, so preparations are necessary to your workflow. Expected time consumption is less than an hour. You will do the following: -- Find and enter some key model metadata into ``global_variables.yml`` -- Include an ERT workflow for establishing case metadata -- Include one script for data export + + * Find and enter some key model metadata into ``global_variables.yml`` + * Include an ERT workflow for establishing case metadata + * Include one script for data export You may also find it helpful to look at the Drogon tutorial project for this. This is in the category "really easy when you know how to do it" so don't hesitate to ask for help! @@ -18,7 +19,7 @@ Insert key model metadata into global_variables.yml In ``fmuconfig/input/``, create ``_masterdata.yml``. The content of this file shall be references to master data. We get our master data from SMDA, so you need to do some lookups there to find your masterdata references. In the FMU metadata, we currently use -4 master data entries: country, discovery, field, coordinate_system and stratigraphic_column. +5 master data entries: country, discovery, field, coordinate_system and stratigraphic_column. .. note:: Master data are "data about the business entities that provide context for business @@ -29,7 +30,7 @@ lookups there to find your masterdata references. In the FMU metadata, we curren fact, referring to the same thing. An example is the country of Norway. Simply saying "Norway" is not enough. We can also refer to Norway as "Norge", "Noreg", "Norga", "Vuodna" or "Nöörje". So, we define a universally unique identifier for the entity of - Norway, and we refer to this instead. And all that various names are *properties* on + Norway, and we refer to this instead. And all those various names are *properties* on this commonly defined entity. These definitions, we store as *master data* because no single applications shall own this definition. @@ -39,21 +40,21 @@ This is the content of ``_masterdata.yml`` from the Drogon example. Adjust to yo .. code-block:: yaml smda: - country: - - identifier: Norway - uuid: ad214d85-8a1d-19da-e053-c918a4889309 - discovery: - - short_identifier: DROGON - uuid: ad214d85-8a1d-19da-e053-c918a4889309 - field: - - identifier: DROGON + country: + - identifier: Norway + uuid: ad214d85-8a1d-19da-e053-c918a4889309 + discovery: + - short_identifier: DROGON + uuid: ad214d85-8a1d-19da-e053-c918a4889309 + field: + - identifier: DROGON + uuid: 00000000-0000-0000-0000-000000000000 + coordinate_system: + identifier: ST_WGS84_UTM37N_P32637 + uuid: ad214d85-dac7-19da-e053-c918a4889309 + stratigraphic_column: + identifier: DROGON_HAS_NO_STRATCOLUMN uuid: 00000000-0000-0000-0000-000000000000 - coordinate_system: - identifier: ST_WGS84_UTM37N_P32637 - uuid: ad214d85-dac7-19da-e053-c918a4889309 - stratigraphic_column: - identifier: DROGON_HAS_NO_STRATCOLUMN - uuid: 00000000-0000-0000-0000-000000000000 Note that ``country``, ``discovery`` and ``field`` are lists. Most of us will only need one entry in the list, but in some cases, more will be required. E.g. if a model is covering @@ -111,8 +112,10 @@ In example below, observe that "TopVolantis" is a home-made name for ``VOLANTIS and is in the stratigraphic column, while "Seabed" is not. In addition, you may want to use some of the *optional* values: -- `alias` is a list of known aliases for this stratigraphic entity. -- `stratigraphic_alias` is a list of valid *stratigraphic* aliases for this entry, e.g. when a specific horizon is the top of both a formation and a group, or similar. + + * ``alias`` is a list of known aliases for this stratigraphic entity. + * ``stratigraphic_alias`` is a list of valid *stratigraphic* aliases for this entry, e.g. when a + * | specific horizon is the top of both a formation and a group, or similar. From the Drogon tutorial: @@ -250,7 +253,9 @@ To verify that data export now works, add one job to your workflow. Pick somethi such as depth surfaces from the structural model or similar. Use one of the examples on the next page to get going, and/or have a look at the Drogon tutorial project. -**What about Sumo** +What about Sumo? +~~~~~~~~~~~~~~~~ + Odds are that you are implementing rich metadata export so that you can start utilizing Sumo. Producing metadata with exported data is a pre-requisite for using Sumo. When you have undertaken the steps above, you are good to go! Head to the diff --git a/src/fmu/dataio/dataio.py b/src/fmu/dataio/dataio.py index 90eeaa5b5..17e3385ce 100644 --- a/src/fmu/dataio/dataio.py +++ b/src/fmu/dataio/dataio.py @@ -380,7 +380,7 @@ class ExportData: Args: access_ssdl: Optional. A dictionary that will overwrite or append - to the default ssdl settings read from the config. Example: + to the default ssdl settings read from the config. Example: ``{"access_level": "restricted", "rep_include": False}`` casepath: To override the automatic and actual ``rootpath``. Absolute path to