Generalize result values of all Indicators by introducing a result class value

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Current Main
 
+### New Features
+
+- Generalize result values of all Indicators by introducing a result class value ([#369])
+
 ### Breaking Changes
 
 - Rename environment variable `OHSOME_API` to `OQT_OHSOME_API` ([#255])
@@ -40,7 +44,9 @@
 - Rename environment variable `OHSOME_API`  `OQT_OHSOME_API` ([#255])
 - Make sure to rename the API query parameter `layerName` to `layerKey` and API endpoint `listLayerNames` to `listLayerKeys` ([#376])
 - To continue to retrieve the properties of the GeoJSON API response as flat list, you need to set the API request parameter `flattem` to `True` ([#375])
+- If you run your own database, please delete the result table before upgrading ([#369])
 - Rename endpoints ([#397]):
+
 | old                          | new                            |
 | ---                          | ---                            |
 | `indicatorLayerCombinations` | `indicator-layer-combinations` |
@@ -54,6 +60,7 @@
 [#342]: https://github.com/GIScience/ohsome-quality-analyst/pull/342
 [#356]: https://github.com/GIScience/ohsome-quality-analyst/pull/356
 [#357]: https://github.com/GIScience/ohsome-quality-analyst/pull/357
+[#369]: https://github.com/GIScience/ohsome-quality-analyst/pull/369
 [#370]: https://github.com/GIScience/ohsome-quality-analyst/pull/370
 [#375]: https://github.com/GIScience/ohsome-quality-analyst/pull/375
 [#376]: https://github.com/GIScience/ohsome-quality-analyst/pull/376
@@ -74,6 +81,7 @@
 [#379]: https://github.com/GIScience/ohsome-quality-analyst/pull/379
 
 
+
 ## 0.10.0
 
 ### Bug Fixes

docs/indicator_creation.md

@@ -15,13 +15,15 @@ As you can see, the indicator you are trying to create should inherit from BaseI
 
 ### Result
 
-The result object can hold 4 values. 
-
-1. label: This should be a member of `TrafficLightQualityLevels` found in [workers/ohsome_quality_analyst/utils/definitions.py](/workers/ohsome_quality_analyst/utils/definitions.py)
-2. value: TBD
-3. description: label description for `TrafficLightQualityLevel` (see metadata.yaml in part 2)
-4. svg: unique file path which is **automatically** created upon object initialization by the `BaseIndicator`
-
+The result object consists of following attributes:
+
+- `timestamp_oqt (datetime)`: Timestamp of the creation of the indicator
+- `timestamp_osm (datetime)`: Timestamp of the used OSM data (e.g. the latest timestamp of the ohsome API results)
+- `label (str)`: Traffic lights like quality label: `green`, `yellow` or `red`. The value is determined by the result classes
+- `value (float)`: The result value
+- `class (int)`: The result class. An integer between 1 and 5. It maps to the result labels: `1` maps to `red`, `2`/`3` map to `yellow` and `4`/`5` map to `green`.  This value is used by the reports to determine an overall result.
+- `description (str)`: The result description.
+- `svg (str)`: Figure of the result as SVG
 
 ### Layer
 

workers/ohsome_quality_analyst/base/indicator.py

@@ -1,7 +1,4 @@
-"""
-TODO:
-    Describe this module and how to implement child classes
-"""
+"""The base classes on which every indicator class is based on."""
 
 import json
 from abc import ABCMeta, abstractmethod
@@ -41,19 +38,28 @@ class Result:
         timestamp_oqt (datetime): Timestamp of the creation of the indicator
         timestamp_osm (datetime): Timestamp of the used OSM data
             (e.g. Latest timestamp of the ohsome API results)
-        label (str): Traffic lights like quality label
-        value (float): The result value as float ([0, 1])
-        description (str): Description of the result
+        label (str): Traffic lights like quality label: `green`, `yellow` or `red`. The
+            value is determined by the result classes
+        value (float): The result value
+        class_ (int): The result class. An integer between 1 and 5. It maps to the
+            result labels. This value is used by the reports to determine an overall
+            result.
+        description (str): The result description.
         svg (str): Figure of the result as SVG
     """
 
-    timestamp_oqt: datetime
-    timestamp_osm: Optional[datetime]
-    label: Literal["green", "yellow", "red", "undefined"]
-    value: Optional[float]
     description: str
     svg: str
     html: str
+    timestamp_oqt: datetime = datetime.now(timezone.utc)  # UTC datetime object
+    timestamp_osm: Optional[datetime] = None
+    value: Optional[float] = None
+    class_: Optional[Literal[1, 2, 3, 4, 5]] = None
+
+    @property
+    def label(self) -> Literal["green", "yellow", "red", "undefined"]:
+        labels = {1: "red", 2: "yellow", 3: "yellow", 4: "green", 5: "green"}
+        return labels.get(self.class_, "undefined")
 
 
 class BaseIndicator(metaclass=ABCMeta):
@@ -70,11 +76,6 @@ def __init__(
         metadata = get_metadata("indicators", type(self).__name__)
         self.metadata: Metadata = from_dict(data_class=Metadata, data=metadata)
         self.result: Result = Result(
-            # UTC datetime object representing the current time.
-            timestamp_oqt=datetime.now(timezone.utc),
-            timestamp_osm=None,
-            label="undefined",
-            value=None,
             description=self.metadata.label_description["undefined"],
             svg=self._get_default_figure(),
             html="",
@@ -90,6 +91,9 @@ def as_feature(self, flatten: bool = False, include_data: bool = False) -> Featu
             flatten (bool): If true flatten the properties.
             include_data (bool): If true include additional data in the properties.
         """
+        result = asdict(self.result)  # only attributes, no properties
+        result["label"] = self.result.label  # label is a property
+        result["class"] = result.pop("class_")
         properties = {
             "metadata": {
                 "name": self.metadata.name,
@@ -100,7 +104,7 @@ def as_feature(self, flatten: bool = False, include_data: bool = False) -> Featu
                 "name": self.layer.name,
                 "description": self.layer.description,
             },
-            "result": asdict(self.result),
+            "result": result,
             **self.feature.properties,
         }
         if include_data:

workers/ohsome_quality_analyst/geodatabase/client.py

@@ -78,7 +78,7 @@ async def save_indicator_results(
         feature_id,
         indicator.result.timestamp_oqt,
         indicator.result.timestamp_osm,
-        indicator.result.label,
+        indicator.result.class_,
         indicator.result.value,
         indicator.result.description,
         indicator.result.svg,
@@ -128,7 +128,7 @@ async def load_indicator_results(
 
     indicator.result.timestamp_oqt = query_result["timestamp_oqt"]
     indicator.result.timestamp_osm = query_result["timestamp_osm"]
-    indicator.result.label = query_result["result_label"]
+    indicator.result.class_ = query_result["result_class"]
     indicator.result.value = query_result["result_value"]
     indicator.result.description = query_result["result_description"]
     indicator.result.svg = query_result["result_svg"]

workers/ohsome_quality_analyst/geodatabase/create_results_table.sql

@@ -5,7 +5,7 @@ CREATE TABLE IF NOT EXISTS results (
     fid text,
     timestamp_oqt timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     timestamp_osm timestamp with time zone,
-    result_label text,
+    result_class integer,
     result_value float,  -- VALUE is an SQL keyword
     result_description text,
     result_svg text,

workers/ohsome_quality_analyst/geodatabase/load_results.sql

@@ -5,7 +5,7 @@ SELECT
     fid,
     timestamp_oqt,
     timestamp_osm,
-    result_label,
+    result_class,
     result_value,
     result_description,
     result_svg,

workers/ohsome_quality_analyst/geodatabase/save_results.sql

@@ -5,7 +5,7 @@ INSERT INTO results (
     fid,
     timestamp_oqt,
     timestamp_osm,
-    result_label,
+    result_class,
     result_value,
     result_description,
     result_svg,
@@ -31,14 +31,14 @@ ON CONFLICT (
         (
             timestamp_oqt,
             timestamp_osm,
-            result_label,
+            result_class,
             result_value,
             result_description,
             result_svg,
             feature) = (
             excluded.timestamp_oqt,
             excluded.timestamp_osm,
-            excluded.result_label,
+            excluded.result_class,
             excluded.result_value,
             excluded.result_description,
             excluded.result_svg,

workers/ohsome_quality_analyst/indicators/building_completeness/indicator.py

@@ -137,32 +137,26 @@ def calculate(self) -> None:
             self.completeness_ratio,
             weights=self.building_area_prediction,
         )
-        description = Template(self.metadata.result_description).substitute(
-            building_area_osm=round(sum(self.building_area_osm), 2),
-            building_area_prediction=round(sum(self.building_area_prediction), 2),
-            completeness_ratio=round(self.result.value * 100, 2),
-        )
         if self.result.value >= self.threshhold_green():
-            self.result.label = "green"
-            self.result.description = (
-                description + self.metadata.label_description["green"]
-            )
+            self.result.class_ = 5
         elif self.result.value >= self.threshhold_yellow():
-            self.result.label = "yellow"
-            self.result.description = (
-                description + self.metadata.label_description["yellow"]
-            )
+            self.result.class_ = 3
         elif 0.0 <= self.result.value < self.threshhold_yellow():
-            self.result.label = "red"
-            self.result.description = (
-                description + self.metadata.label_description["red"]
-            )
+            self.result.class_ = 1
         else:
             raise ValueError(
                 "Result value (percentage mapped) is an unexpected value: {}".format(
                     self.result.value
                 )
             )
+        description = Template(self.metadata.result_description).substitute(
+            building_area_osm=round(sum(self.building_area_osm), 2),
+            building_area_prediction=round(sum(self.building_area_prediction), 2),
+            completeness_ratio=round(self.result.value * 100, 2),
+        )
+        self.result.description = (
+            description + self.metadata.label_description[self.result.label]
+        )
 
     def create_figure(self) -> None:
         if self.result.label == "undefined":

workers/ohsome_quality_analyst/indicators/currentness/indicator.py

@@ -131,17 +131,17 @@ def calculate(self) -> None:
         )
 
         if self.result.value >= self.threshold_yellow:
-            self.result.label = "green"
+            self.result.class_ = 5
             self.result.description = (
                 self.result.description + self.metadata.label_description["green"]
             )
         elif self.result.value >= self.threshold_red:
-            self.result.label = "yellow"
+            self.result.class_ = 3
             self.result.description = (
                 self.result.description + self.metadata.label_description["yellow"]
             )
         elif self.result.value < self.threshold_red:
-            self.result.label = "red"
+            self.result.class_ = 1
             self.result.description = (
                 self.result.description + self.metadata.label_description["red"]
             )

workers/ohsome_quality_analyst/indicators/ghs_pop_comparison_buildings/indicator.py

@@ -25,7 +25,6 @@ def __init__(self, layer: Layer, feature: Feature) -> None:
         self.area = None
         self.pop_count_per_sqkm = None
         self.feature_count = None
-        self.feature_count_per_sqkm = None
 
     @classmethod
     def attribution(cls) -> str:
@@ -57,50 +56,41 @@ async def preprocess(self) -> None:
         self.feature_count = query_results["result"][0]["value"]
         timestamp = query_results["result"][0]["timestamp"]
         self.result.timestamp_osm = dateutil.parser.isoparse(timestamp)
-        self.feature_count_per_sqkm = self.feature_count / self.area
         self.pop_count_per_sqkm = self.pop_count / self.area
 
     def calculate(self) -> None:
+        self.result.value = self.feature_count / self.area  # feature_count_per_sqkm
         description = Template(self.metadata.result_description).substitute(
             pop_count=round(self.pop_count),
             area=round(self.area, 1),
             pop_count_per_sqkm=round(self.pop_count_per_sqkm, 1),
-            feature_count_per_sqkm=round(self.feature_count_per_sqkm, 1),
+            feature_count_per_sqkm=round(self.result.value, 1),
         )
 
         if self.pop_count_per_sqkm == 0:
             return
 
-        elif self.feature_count_per_sqkm <= self.yellow_threshold_function(
+        elif self.result.value <= self.yellow_threshold_function(
             self.pop_count_per_sqkm
         ):
-            self.result.value = (
-                self.feature_count_per_sqkm
-                / self.yellow_threshold_function(self.pop_count_per_sqkm)
-            ) * (0.5)
+            self.result.class_ = 1
             self.result.description = (
                 description + self.metadata.label_description["red"]
             )
-            self.result.label = "red"
 
-        elif self.feature_count_per_sqkm <= self.green_threshold_function(
+        elif self.result.value <= self.green_threshold_function(
             self.pop_count_per_sqkm
         ):
-            green = self.green_threshold_function(self.pop_count_per_sqkm)
-            yellow = self.yellow_threshold_function(self.pop_count_per_sqkm)
-            fraction = (self.feature_count_per_sqkm - yellow) / (green - yellow) * 0.5
-            self.result.value = 0.5 + fraction
+            self.result.class_ = 3
             self.result.description = (
                 description + self.metadata.label_description["yellow"]
             )
-            self.result.label = "yellow"
 
         else:
-            self.result.value = 1.0
+            self.result.class_ = 5
             self.result.description = (
                 description + self.metadata.label_description["green"]
             )
-            self.result.label = "green"
 
     def create_figure(self) -> None:
         if self.result.label == "undefined":
@@ -148,15 +138,15 @@ def create_figure(self) -> None:
         ax.fill_between(
             x,
             y1,
-            max(max(y1), self.feature_count_per_sqkm),
+            max(max(y1), self.result.value),
             alpha=0.5,
             color="green",
         )
 
         # Plot pont as circle ("o").
         ax.plot(
             self.pop_count_per_sqkm,
-            self.feature_count_per_sqkm,
+            self.result.value,
             "o",
             color="black",
             label="location",