refactor(indicators): separate templates from metadata

separate indicators text templates for label and result description from
metadata.

Author: matthiasschaub

ohsome_quality_api/indicators/attribute_completeness/indicator.py

@@ -67,7 +67,7 @@ def calculate(self) -> None:
             self.result.value = None
         if self.result.value is None:
             return
-        description = Template(self.metadata.result_description).substitute(
+        description = Template(self.templates.result_description).substitute(
             result=round(self.result.value, 2),
             all=round(self.absolute_value_1, 1),
             matched=round(self.absolute_value_2, 1),
@@ -79,17 +79,17 @@ def calculate(self) -> None:
         if self.result.value >= self.threshold_yellow:
             self.result.class_ = 5
             self.result.description = (
-                description + self.metadata.label_description["green"]
+                description + self.templates.label_description["green"]
             )
         elif self.threshold_yellow > self.result.value >= self.threshold_red:
             self.result.class_ = 3
             self.result.description = (
-                description + self.metadata.label_description["yellow"]
+                description + self.templates.label_description["yellow"]
             )
         else:
             self.result.class_ = 1
             self.result.description = (
-                description + self.metadata.label_description["red"]
+                description + self.templates.label_description["red"]
             )
 
     def create_figure(self) -> None:

ohsome_quality_api/indicators/attribute_completeness/metadata.yaml

@@ -8,15 +8,3 @@ attribute-completeness:
       Derive the ratio of OSM features compared to features which
       match additional expected tags (e.g. amenity=hospital vs
       amenity=hospital and wheelchair=yes).
-  label_description:
-    red: >-
-      Less than 25% of the features match the expected tags.
-    yellow: >-
-      Around 25-75% of the features match the expected tags.
-    green: >-
-      More than 75% of the features match the expected tags.
-    undefined: >-
-      The quality level could not be calculated for this indicator.
-  result_description: >-
-    The ratio of the features (all: $all) compared to features with
-    expected tags (matched: $matched) is $result. 

ohsome_quality_api/indicators/attribute_completeness/templates.yaml

@@ -0,0 +1,13 @@
+---
+label_description:
+  red: >-
+    Less than 25% of the features match the expected tags.
+  yellow: >-
+    Around 25-75% of the features match the expected tags.
+  green: >-
+    More than 75% of the features match the expected tags.
+  undefined: >-
+    The quality level could not be calculated for this indicator.
+result_description: >-
+  The ratio of the features (all: $all) compared to features with
+  expected tags (matched: $matched) is $result. 

ohsome_quality_api/indicators/base.py

@@ -1,13 +1,23 @@
 import json
+import os
 from abc import ABCMeta, abstractmethod
 
 import plotly.graph_objects as go
+import yaml
 from geojson import Feature, Polygon
 
 from ohsome_quality_api.definitions import get_attribution, get_metadata
-from ohsome_quality_api.indicators.models import IndicatorMetadata, Result
+from ohsome_quality_api.indicators.models import (
+    IndicatorMetadata,
+    IndicatorTemplates,
+    Result,
+)
 from ohsome_quality_api.topics.models import BaseTopic as Topic
-from ohsome_quality_api.utils.helper import json_serialize
+from ohsome_quality_api.utils.helper import (
+    camel_to_snake,
+    get_module_dir,
+    json_serialize,
+)
 
 
 class BaseIndicator(metaclass=ABCMeta):
@@ -21,10 +31,11 @@ def __init__(
         self.metadata: IndicatorMetadata = get_metadata(
             "indicators", type(self).__name__
         )
+        self.templates: IndicatorTemplates = self.get_template()
         self.topic: Topic = topic
         self.feature: Feature = feature
         self.result: Result = Result(
-            description=self.metadata.label_description["undefined"],
+            description=self.templates.label_description["undefined"],
         )
         self._get_default_figure()
 
@@ -34,10 +45,7 @@ def as_dict(self, include_data: bool = False, exclude_label: bool = False) -> di
         else:
             result = self.result.model_dump(by_alias=True)
         raw_dict = {
-            "metadata": self.metadata.model_dump(
-                by_alias=True,
-                exclude={"result_description", "label_description"},
-            ),
+            "metadata": self.metadata.model_dump(by_alias=True),
             "topic": self.topic.model_dump(
                 by_alias=True,
                 exclude={"ratio_filter"},
@@ -86,6 +94,7 @@ def data(self) -> dict:
         data = vars(self).copy()
         data.pop("result")
         data.pop("metadata")
+        data.pop("templates")
         data.pop("topic")
         data.pop("feature")
         return json.loads(json.dumps(data, default=json_serialize).encode())
@@ -167,3 +176,13 @@ def _get_default_figure(self) -> None:
         raw = fig.to_dict()
         raw["layout"].pop("template")  # remove boilerplate
         self.result.figure = raw
+
+    def get_template(self) -> IndicatorTemplates:
+        """Get template for indicator."""
+        indicator_key = camel_to_snake(type(self).__name__)
+        dir = get_module_dir(f"ohsome_quality_api.indicators.{indicator_key}")
+        file = os.path.join(dir, "templates.yaml")
+        with open(file, "r") as file:
+            raw = yaml.safe_load(file)
+        templates = IndicatorTemplates(**raw)
+        return templates

ohsome_quality_api/indicators/building_comparison/indicator.py

@@ -111,7 +111,7 @@ def calculate(self) -> None:
             edge_case = self.check_minor_edge_cases(key)
             # ZeroDivisionError can not occur because of `check_major_edge_cases()`
             self.ratio[key] = self.area_osm[key] / self.area_ref[key]
-            template = Template(self.metadata.result_description)
+            template = Template(self.templates.result_description)
             description = template.substitute(
                 ratio=round(self.ratio[key] * 100, 2),
                 coverage=round(self.area_cov[key] * 100, 2),
@@ -130,13 +130,13 @@ def calculate(self) -> None:
                 self.result.class_ = 3
             elif self.th_low > self.result.value >= 0:
                 self.result.class_ = 1
-            label_description = self.metadata.label_description[self.result.label]
+            label_description = self.templates.label_description[self.result.label]
             self.result.description = " ".join((label_description, result_description))
         elif major_edge_case:
-            label_description = self.metadata.label_description[self.result.label]
+            label_description = self.templates.label_description[self.result.label]
             self.result.description = " ".join((label_description, result_description))
         else:
-            label_description = self.metadata.label_description[self.result.label]
+            label_description = self.templates.label_description[self.result.label]
             edge_case = (
                 "OSM has substantivly more buildings than the reference datasets. The "
                 "reference dataset is likely to miss many buildings."

ohsome_quality_api/indicators/building_comparison/metadata.yaml

@@ -7,14 +7,3 @@ building-comparison:
   quality_dimension: completeness
   description: >-
     Comparison of OSM buildings with the buildings of reference datasets.
-  label_description:
-    red: >-
-      The completeness of OSM buildings in your area-of-interest is low.
-    yellow: >-
-      The completeness of OSM buildings in your area-of-interest is medium.
-    green: >-
-      The completeness of OSM buildings in your area-of-interest is high.
-    undefined: >-
-      Comparison could not be made.
-  result_description: >-
-    The completeness in comparison to $dataset is $ratio%.

ohsome_quality_api/indicators/building_comparison/templates.yaml

@@ -0,0 +1,12 @@
+---
+label_description:
+  red: >-
+    The completeness of OSM buildings in your area-of-interest is low.
+  yellow: >-
+    The completeness of OSM buildings in your area-of-interest is medium.
+  green: >-
+    The completeness of OSM buildings in your area-of-interest is high.
+  undefined: >-
+    Comparison could not be made.
+result_description: >-
+  The completeness in comparison to $dataset is $ratio%.

ohsome_quality_api/indicators/currentness/indicator.py

@@ -158,9 +158,9 @@ def calculate(self):
         else:
             self.result.class_ = 1
 
-        label_description = self.metadata.label_description[self.result.label]
+        label_description = self.templates.label_description[self.result.label]
         self.result.description += Template(
-            self.metadata.result_description
+            self.templates.result_description
         ).substitute(
             up_to_date_contrib_rel=f"{sum(self.bin_up_to_date.contrib_rel) * 100:.0f}",
             num_of_elements=int(self.contrib_sum),

ohsome_quality_api/indicators/currentness/metadata.yaml

@@ -7,14 +7,3 @@ currentness:
   quality_dimension: currentness
   description: >-
     Estimate currentness of features by classifying contributions based on topic specific temporal thresholds into three groups: up-to-date, in-between and out-of-date.
-  label_description:
-    red: >-
-      Many features are out-of-date.
-    yellow: >-
-      Some features are up-to-date and some features are out-of-date.
-    green: >-
-      Most features are up-to-date.
-    undefined: >-
-      The quality level could not be calculated for this indicator.
-  result_description: >-
-      In the area of interest $up_to_date_contrib_rel% of the $num_of_elements features were edited (created or modified) for the last time in the period between $from_timestamp and $to_timestamp.

ohsome_quality_api/indicators/currentness/templates.yaml

@@ -0,0 +1,12 @@
+---
+label_description:
+  red: >-
+    Many features are out-of-date.
+  yellow: >-
+    Some features are up-to-date and some features are out-of-date.
+  green: >-
+    Most features are up-to-date.
+  undefined: >-
+    The quality level could not be calculated for this indicator.
+result_description: >-
+    In the area of interest $up_to_date_contrib_rel% of the $num_of_elements features were edited (created or modified) for the last time in the period between $from_timestamp and $to_timestamp.