Feedback on OEMetabuilder (bugs & usabillity)

[chrwm]

With the OEP release v.0.11.0 the oemetabuilder was introduced which enables the ontological annotation of metadata via a GUI. This discussion should collect observations and bugs around the tool with the aim of improving its usability. The discussion also serves as a meta summary of issues around the tool.

[chrwm]

I think the usability could be improved when downloading the metadata after editing in the GUI. Null-values are omitted and the field order is changed, which makes it harder to work the metadata.

Issue: #1108
PR:

[jh-RLI]

Thanks @chrwm for starting this discussion:
One thing I would like to add to the OEMetaBuilder is an autocomplete/dropdown function for the keywords field. The keywords represent the OEP tags. Recently, we added a feature to synchronize the tags and keywords when they are added to a data table on the OEP website or to the keyword field. Therefore, it would be useful to provide a user-friendly way to add keywords to metadata by providing a searchable overview of existing keywords/tags. This would work similarly to the function in the isAbout and valueReference fields. User input can be auto-completed based on the tags in the oedb.tags table.

[lumi321]

I recently (10th of november) used the OEMetabuilder to create metadata for some example data. I found a few points to improve or worthy to discuss in terms of best-practice. For a streamlined dicussion, I will post every point as a new comment that you can directly reply to.

---

The first point is that terms from the latest OEO release (1.12.0) are missing i.e., not available in the drop-down menu.

[jh-RLI]

@adelmemariani maybe you can explain this more :) I think the last owl/rdf file is not accessible to the loep? But I'm not really involved in the oeo release.

[adelmemariani]

@adelmemariani maybe you can explain this more :) I think the last owl/rdf file is not accessible to the loep? But I'm not really involved in the oeo release.

The lookup service for the OEMetabuilder tool needs to read OEO and index its internal structure for the final autocomplete suggestions. It reads the full version of the OEO. Therefore for each new release of the OEO, the lookup service needs to index the OEO terms again. Thus, the tool does not cover the new terms from the latest version of the OEO yet.

[lumi321]

Another point is that terms from some of the imported ontologies are missing e.g. dc:identifier.

[chrwm]

@adelmemariani this also might relate to the OEO version embedded in the backend.

[chrwm]

As @lumi321 suggested in a discussion below, it could be due to some terms (e.g. dc:identifier) are imported without definition: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/elements11/identifier/

[lumi321]

Probably a bug: The Fields “name” and “type” in the mask under Resource, Resource 1, Schema, Fields, and Field 1, cannot be accessed. Clicking twice on the menu button next to Field 1 makes the fields look grey.

[jh-RLI]

This is already fixed and staged for release :)

[lumi321]

Great!

[lumi321]

I personally find the usage of “name” a bit irritating as it is inconsistent. If it is not a necessity for further processing, I suggest making clear when a “name” refers to an arbitrary name from a dataset (like in Resource 1 or Field 1) and when it refers to an OEO-concept (like in IsAbout 1 or Value reference 1).

[jh-RLI]

Usually there are tooltips/description text see this similar tool - descriptions are displayed below each field. Currently, this is broken as the JavaScript library that provides core functionality to the OEMetaBuilder does not support bootstrap 5 so far - we are working on a solution. This could help to better understand the use cases for each field.

[jh-RLI]

We are also working on making required, optional and automated fields visible.

[lumi321]

Sounds good! 😀

[lumi321]

It would be quite helpful to have a link to the metadata_key_description.md (https://github.com/OpenEnergyPlatform/oemetadata/blob/master/metadata/latest/metadata_key_description.md) somewhere on the page of the OEMetabuilder. It would facilitate resolving irritations like the one from a previous comment about "name".

[chrwm]

This could be solved with the display of the tooltips (comment above). Or simply by including the metadata_key_description.md link on a suitable place on the website as suggested.

[lumi321]

Perhaps it is intended, but it caught my eye, that there is no possibility to annotate the Unit of a Field.

[jh-RLI]

I think we should allow annotating the "unit" field of the oemetadata. @chrwm @Ludee

[chrwm]

The context.json - to interprete our OEMetadata as JSON-LD - already covers the "unit" field with: oeo:OEO_00040010 -> has unit.
Thus, already today the field could be sparqled, however, the results will not be OEO-conform if we don't ease uniform annotation with the OEO in OEMetabuilder.

Option 1
In the OEMetadata we could leave the "unit" field untouched and in the OEMetabuilder we could enable auto-complete, just as in the other ontological fields. In the current state then we would need to decide if we pass the "name" (rdfs:label) or "path" (URI) information into the "unit" field. In this case I'd argue for the "name" information to keep the field human-readable.

Option 2
We could do that add "unit"- sub-fields "name" & "path", similar to isAbout. This would be a bigger change in the metadata.

[chrwm]

Currently, I lean towards Option 1 to keep the metadata simple.

[jh-RLI]

I also like option 1 - if the rdfs:label is unique to the uri then this should be enough. We would still have to update the metadata key description at least to make this decision reproducible for oemetadata use-cases outside the OEMetaBuilder. If there are cases where we need multiple oeo terms to annotate the value of unit (is this a case?) then we would need the isAbout.

[lumi321]

There is no possibility to link several OEO-concepts to one parameter value. In some cases, where there is no exact matching OEO-concept, this might be insufficient.

[jh-RLI]

As far as i understand, the question is: Should we allow multiple oeo-concept references for single values. @chrwm @Ludee

[chrwm]

The problem is common for ontologies.
This is related to composed concepts and this issue: OpenEnergyPlatform/ontology#1328 (comment)
Two options are discussed.

1. Option: Create new concept in OEO if value cannot be described with OEO-term.
2. Option: Allow users to create triples during annotation with on-thy-fly annotation tool.

A simple concatenation or listing of terms, e.g. heat + efficiency -> heat efficiency seems unrealistic, since no unique RDF triples can be formed that are necessary for saving.

The options are discussed currently.

[lumi321]

Regarding the valueReference, values like “all”, “total” and “other” are difficult to annotate. For “total” the concept “integral” could be used, but for “all” and “other” I have no good idea. Is there a best practice?

[chrwm]

“all”, “total” and “other” are very generic and need additional information to be put in context don't seem to be specific to the energy domain.
From my perspective this is rather an issue of data structuring than the ontology.

[lumi321]

How should information from the table title be handled?
Example: table name “energy demand by fuel” and columns “diesel”, “jet fuel” etc. Should the OEO-concept “fuel demand” be added to “diesel”, together with the OEO-concept for diesel, or should this information be placed somewhere else in the Metadata, for example in subject?

[chrwm]

The subject field is intended to ontologically describe the content of the whole table in a more general fashion. Thus, in your case "fuel demand" in the subject field seems suitable for the context you provided.

[lumi321]

I saw this problem should not occur, when following step 6d of this tutorial (https://openenergy-platform.org/tutorials/7/), but it might be worth to highlight that in a suitable place for example the metadata_key_description.md.

Value-year-problem: Imagine a table with following columns: parameter, unit, and one column each for the years from 2000 to 2022. How should the column “2015” be annotated? The column “2015” holds the value of a given parameter with a given unit for the year 2015. Annotation with “scenario year” or with “quantity value” or both or something else?

[lumi321]

Specific subsets of OEO classes: Is there a good way to annotate “this parameter in the dataset refers to everything in OEO class X except subclass Y”?
Example: internal combustion vehicles without gas vehicles. The workaround seems to be listing only all possible subclasses in the annotation, but this could lead to lengthy lists.

[lumi321]

Sometimes it was unclear to me which OEO-concept I should choose. Examples: different types of regions, typical year vs. scenario year.
One example worth highlighting is the annotation of “ID”. In some examples on the OEP, I saw that dc:identifier was used. Since “ID” (or an equivalent label) occurs quite often, it might be worth to add a general recommendation for how to annotate “ID”.

[lumi321]

Unit with prefix annotation: If units have a prefix such as kilo, giga etc. it is usually appended to the unit with k-, g- etc. and this way a part of the unit. Sometimes it happens that there is column with a certain measurement magnitude e.g., column “passengers (thousand)”. How should the “thousand” in such a case be handled? As a kilo to the unit like a normal prefix or as a kilo-concept to the parameter reference?

[chrwm]

I'd say without having seen the data thousand correponds to the number of passengers here. So the unit should be thousand passengers. Is a rather specific unit or does it occur more frequently in energy mobility modelling?
If the latter it might be worth adding to the OEO.

Issue: OpenEnergyPlatform/ontology#1402
PR:

[lumi321]

Not all terms that are imported in the OEO have a definition and thus don't/won't show it in the drop-down menu. I am not sure how many of the terms without definition are actually relevant for annotating. It seems that most of them are owl annotation properties.
It might be good to collect relevant terms and ask the OEO devs to add definitions for them.
One example is 'dc:identifier', which is used for annotating "ID" in some examples but lacks a definition.

[chrwm]

Discussion is connected and is continued in discussion above: #1107 (comment)

[FelixMau]

Importing Datatemplates with null values deletes key value pair. I think this should be avoided because it might be important for null values as well that the key is kept?

If the apply button gets hit again, the field is disappearing completly

[FelixMau]

Unfortunately it is not visible, that the ID field is grey (as mentioned above) and not editable.

[chrwm]

I agree omitting fields with null values should be changed! I also overserved it and find it quite annoying. Here is the corresponding

Issue: #1108
PR:

[chrwm]

Currently, the suggestion of OEO terms does not work for the subject field.

[jh-RLI]

I added this in #1119 - i will merge it but cant test this as i dont have the lookup service installed