Add scaling/normalisation of KPI outputs

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] -
+
+### Added
+
+- Normalisation to values between `0` and `10` for metrics ([#69](https://github.com/arup-group/gelato/issues/69)): 
+`Affordability`, `PT Wait Time`, `Occupancy`, `GHG`, `Travel Time`, `Access to Mobility services`, `Congestion`
+
+### Fixed
+
+- GHG Emissions KPI under-reporting bug ([#73](https://github.com/arup-group/gelato/issues/73))
+
+### Changed
+
+-
 
 ## [0.0.3-alpha] - 2024-03-07
 

src/main/java/com/arup/cml/abm/kpi/KpiCalculator.java

@@ -3,29 +3,30 @@
 import tech.tablesaw.api.Table;
 
 import java.nio.file.Path;
+import java.util.Map;
 
 public interface KpiCalculator {
-    double writeAffordabilityKpi(Path outputDirectory);
+    Map<String, Double> writeAffordabilityKpi(Path outputDirectory, Normaliser normaliser);
 
-    void writePtWaitTimeKpi(Path outputDirectory);
+    Map<String, Double> writePtWaitTimeKpi(Path outputDirectory, Normaliser normaliser);
 
     void writeModalSplitKpi(Path outputDirectory);
 
-    void writeOccupancyRateKpi(Path outputDirectory);
+    Map<String, Double> writeOccupancyRateKpi(Path outputDirectory, Normaliser normaliser);
 
     double writeVehicleKMKpi(Path outputDirectory);
 
     void writePassengerKMKpi(Path outputDirectory);
 
     void writeSpeedKpi(Path outputDirectory);
 
-    double writeGHGKpi(Path outputDirectory);
+    Map<String, Double> writeGHGKpi(Path outputDirectory, Normaliser normaliser);
 
-    double writeTravelTimeKpi(Path outputDirectory);
+    Map<String, Double> writeTravelTimeKpi(Path outputDirectory, Normaliser normaliser);
 
-    Table writeAccessToMobilityServicesKpi(Path outputDirectory);
+    Map<String, Map<String, Double>> writeAccessToMobilityServicesKpi(Path outputDirectory, Normaliser normaliser);
 
-    Table writeCongestionKpi(Path directory);
+    Table writeCongestionKpi(Path directory, Normaliser normaliser);
 
     double writeMobilitySpaceUsageKpi(Path outputDirectory);
 }

src/main/java/com/arup/cml/abm/kpi/LinearNormaliser.java

@@ -0,0 +1,91 @@
+package com.arup.cml.abm.kpi;
+
+public class LinearNormaliser implements Normaliser {
+    private double leftIntervalBound;
+    private double rightIntervalBound;
+    private double leftValueBound;
+    private double rightValueBound;
+    private boolean isReversed = false;
+
+    /**
+     * Provides 1D affine transformation: M * value + C
+     * mapping values: [leftValueBound, rightValueBound] -> [leftIntervalBound, rightIntervalBound]
+     * leftValueBound can be larger than rightValueBound, a given value will be scaled reversely.
+     * Values outside the boundaries, are mapped to their closest bound.
+     * E.g.
+     * If [0, 1] -> [0, 10] then 0.4 -> 4, -5 -> 0, 2 -> 10
+     * If [1, 0] -> [0, 10] then 0.4 -> 6, -5 -> 10, 2 -> 0
+     * @param leftIntervalBound left bound of the destination interval,
+     *                          leftIntervalBound < rightIntervalBound, necessarily.
+     * @param rightIntervalBound right bound of the destination interval,
+     *                           rightIntervalBound > leftIntervalBound, necessarily.
+     * @param leftValueBound left bound of the origin interval, it is mapped to leftIntervalBound.
+     * @param rightValueBound right bound of the origin interval, it is mapped to rightIntervalBound.
+     */
+    public LinearNormaliser(double leftIntervalBound, double rightIntervalBound, double leftValueBound, double rightValueBound) {
+        if (leftIntervalBound > rightIntervalBound) {
+            throw new IllegalArgumentException("leftIntervalBound cannot be larger than rightValueBound");
+        }
+        if (leftValueBound == rightValueBound && leftIntervalBound != rightIntervalBound) {
+            throw new IllegalArgumentException("The bounds given for linear interval are invalid. " +
+                    "Left and right bounds cannot both be the same value.");
+        }
+        if (leftValueBound > rightValueBound) {
+            this.isReversed = true;
+            leftValueBound = -leftValueBound;
+            rightValueBound = -rightValueBound;
+        }
+
+        this.leftIntervalBound = leftIntervalBound;
+        this.rightIntervalBound = rightIntervalBound;
+        this.leftValueBound = leftValueBound;
+        this.rightValueBound = rightValueBound;
+    }
+
+    /**
+     * Provides 1D affine transformation: M * value + C
+     * mapping values: [leftValueBound, rightValueBound] -> [0, 10]
+     * leftValueBound can be larger than rightValueBound, a given value will be scaled reversely.
+     * Values outside the boundaries, are mapped to their closest bound.
+     * E.g.
+     * If [0, 1] -> [0, 10] then 0.4 -> 4, -5 -> 0, 2 -> 10
+     * If [1, 0] -> [0, 10] then 0.4 -> 6, -5 -> 10, 2 -> 0
+     * @param leftValueBound left bound of the origin interval, it is mapped to 0.
+     * @param rightValueBound right bound of the origin interval, it is mapped to 10.
+     */
+    public LinearNormaliser(double leftValueBound, double rightValueBound) {
+        this(0, 10, leftValueBound, rightValueBound);
+    }
+
+    private boolean isReversed() {
+        return this.isReversed;
+    }
+
+    public double getLowerIntervalBound() {
+        return leftIntervalBound;
+    }
+
+    public double getUpperIntervalBound() {
+        return rightIntervalBound;
+    }
+
+    private boolean isWithinBounds(double value) {
+        return value >= leftValueBound && value <= rightValueBound;
+    }
+
+    @Override
+    public double normalise(double value) {
+        if (this.isReversed()) {
+            value = -value;
+        }
+        if (this.isWithinBounds(value)) {
+            return ((value - leftValueBound) / (rightValueBound - leftValueBound)) * (rightIntervalBound - leftIntervalBound);
+        } else {
+            if (value > rightValueBound) {
+                return rightIntervalBound;
+            } else {
+                return leftIntervalBound;
+            }
+        }
+    }
+}

src/main/java/com/arup/cml/abm/kpi/Normaliser.java

@@ -0,0 +1,5 @@
+package com.arup.cml.abm.kpi;
+
+public interface Normaliser {
+    double normalise(double value);
+}

src/main/java/com/arup/cml/abm/kpi/matsim/run/MatsimKpiGenerator.java

@@ -1,6 +1,7 @@
 package com.arup.cml.abm.kpi.matsim.run;
 
 import com.arup.cml.abm.kpi.KpiCalculator;
+import com.arup.cml.abm.kpi.LinearNormaliser;
 import com.arup.cml.abm.kpi.data.MoneyLog;
 import com.arup.cml.abm.kpi.domain.NetworkLinkLog;
 import com.arup.cml.abm.kpi.matsim.MatsimUtils;
@@ -92,17 +93,20 @@ public void run() {
                 CompressionType.gzip
         );
 
-        kpiCalculator.writeAffordabilityKpi(outputDir);
-        kpiCalculator.writePtWaitTimeKpi(outputDir);
+        double leftIntervalBound = 0.0;
+        double rightIntervalBound = 10.0;
+        double secondsInAMinute = 60.0;
+        kpiCalculator.writeAffordabilityKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 1.25, 1));
+        kpiCalculator.writePtWaitTimeKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 15 * secondsInAMinute, 5 * secondsInAMinute));
         kpiCalculator.writeModalSplitKpi(outputDir);
-        kpiCalculator.writeOccupancyRateKpi(outputDir);
+        kpiCalculator.writeOccupancyRateKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 0.2, 0.6));
         kpiCalculator.writeVehicleKMKpi(outputDir);
         kpiCalculator.writePassengerKMKpi(outputDir);
         kpiCalculator.writeSpeedKpi(outputDir);
-        kpiCalculator.writeGHGKpi(outputDir);
-        kpiCalculator.writeAccessToMobilityServicesKpi(outputDir);
-        kpiCalculator.writeCongestionKpi(outputDir);
-        kpiCalculator.writeTravelTimeKpi(outputDir);
+        kpiCalculator.writeGHGKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 8.87, 0.0));
+        kpiCalculator.writeAccessToMobilityServicesKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 0.0, 100.0));
+        kpiCalculator.writeCongestionKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 3.0, 1.25));
+        kpiCalculator.writeTravelTimeKpi(outputDir, new LinearNormaliser(leftIntervalBound, rightIntervalBound, 90.0, 10.0));
         kpiCalculator.writeMobilitySpaceUsageKpi(outputDir);
         MemoryObserver.stop();
     }