Add functionality to calculate average of observations

Add logic for calculating the average (arithmetic mean) of observations

public/js/src_modules/aggregate.mjs

@@ -2,12 +2,12 @@
 
 /**
  * Create 24-hour time strings for a time interval delimited by a start time and an end time. It is assumed that the start time is at "00:00:00" and the end time is at "23:45:00" (when the sampling rate of observations is 15 min) or "23:00:00" (when the sampling rate of observations is 60 min)
- * @param {String} phenomenonSamplingRate The sampling rate of the phenomenon of interest represented as a string, e.g. "15 min", "60 min"
+ * @param {String} phenomenonSamplingRate The sampling rate of the phenomenon of interest represented as a string, e.g. "15min", "60min"
  * @returns {Array} An array of two 24-hour strings representing the start time and end time
  */
 const createTimeStringsForInterval = function (phenomenonSamplingRate) {
-  const fifteenMinutes = "15 min";
-  const sixtyMinutes = "60 min";
+  const fifteenMinutes = "15min";
+  const sixtyMinutes = "60min";
 
   const startTime = "00:00:00";
   const endTimeFifteenMinutes = "23:45:00";
@@ -17,7 +17,9 @@ const createTimeStringsForInterval = function (phenomenonSamplingRate) {
     phenomenonSamplingRate !== fifteenMinutes &&
     phenomenonSamplingRate !== sixtyMinutes
   )
-    return;
+    throw new Error(
+      `Check that the provided phenomenon sampling rate string is in this format: "15min" or "60min"`
+    );
 
   // 15 min sampling rate
   if (phenomenonSamplingRate === fifteenMinutes) {
@@ -49,7 +51,7 @@ const createIso8601DateTimeString = function (
  * @returns {Boolean} true if leap year, false if not
  */
 const checkIfLeapYear = function (year) {
-  return (year % 4 == 0 && year % 100 != 0) || year % 400 == 0;
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
 };
 
 /**
@@ -74,28 +76,22 @@ const getIndexOfTimestamp = function (inputTimestampArr, timestampOfInterest) {
 };
 
 /**
- * Calculate the sum of observation values within a time interval delimited by a start date and end date. The start date may be the same as the end date.
- * @param {Array} obsArray An array of observations (timestamp + value) that is response from SensorThings API
- * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15 min", "60 min"
+ * Calculate the indexes of the start and end timestamps
+ * @param {Array} obsTimestampArr An array of observations timestamps
+ * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15min", "60min"
  * @param {String} startDate A 24-hour date string representing the start date
  * @param {String} endDate A 24-hour date string representing the end date
- * @returns {Number} A floating-point number representing the sum of observation values
+ * @returns {Array} A 1*2 array tht contains integers representing the start index and end index respectively
  */
-const calculateSumOfObservationValuesWithinDatesInterval = function (
-  obsArray,
+const calculateIndexStartEndTimestamp = function (
+  obsTimestampArr,
   samplingRate,
   startDate,
   endDate
 ) {
-  // Extract the timestamps and values from the observations
-  const obsTimestampArr = obsArray.map((obs) => obs[0]);
-  const obsValuesArr = obsArray.map((obs) => obs[1]);
-
-  // Create array of 24-hour strings for the start and end of interval
-  const startPlusEndTimeStrings = createTimeStringsForInterval(samplingRate);
-
-  // Extract 24-hour strings for the start and end of interval
-  const [startTimeString, endTimeString] = startPlusEndTimeStrings;
+  // Create and extract 24-hour strings for the start and end of interval
+  const [startTimeString, endTimeString] =
+    createTimeStringsForInterval(samplingRate);
 
   // Create ISO 8601 strings for the start and end of interval
   const startIso8601DateTimeString = createIso8601DateTimeString(
@@ -117,27 +113,74 @@ const calculateSumOfObservationValuesWithinDatesInterval = function (
     endIso8601DateTimeString
   );
 
+  return [indexStartTimestamp, indexEndTimestamp];
+};
+
+/**
+ * Extract the set of observation values that fall within a time interval delimited by a start date and end date. The start date may be the same as the end date.
+ * @param {Array} obsArray An array of observations (timestamp + value) that is response from SensorThings API
+ * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15min", "60min"
+ * @param {String} startDate A 24-hour date string representing the start date
+ * @param {String} endDate A 24-hour date string representing the end date
+ * @returns {Array} An array of observation values that fall within our time interval
+ */
+const extractObservationValuesWithinDatesInterval = function (
+  obsArray,
+  samplingRate,
+  startDate,
+  endDate
+) {
+  // Extract the timestamps and values from the observations
+  const obsTimestampArr = obsArray.map((obs) => obs[0]);
+  const obsValuesArr = obsArray.map((obs) => obs[1]);
+
+  // Calculate the indexes of the timestamps for the start and end of interval
+  const [indexStartTimestamp, indexEndTimestamp] =
+    calculateIndexStartEndTimestamp(
+      obsTimestampArr,
+      samplingRate,
+      startDate,
+      endDate
+    );
+
   // Extract the observations that fall within our time interval
-  const obsValuesForTimeIntervalArr = obsValuesArr.slice(
-    indexStartTimestamp,
-    indexEndTimestamp + 1
-  );
+  return obsValuesArr.slice(indexStartTimestamp, indexEndTimestamp + 1);
+};
 
-  return obsValuesForTimeIntervalArr.reduce(
+/**
+ * Calculate the sum of observation values that fall within a time interval delimited by a start date and end date
+ * @param {Array} obsValuesForDaysIntervalArr An array of observation values that fall within our time interval
+ * @returns {Number} A floating-point number representing the sum of observation values
+ */
+const calculateSumOfObservationValuesWithinDatesInterval = function (
+  obsValuesForDaysIntervalArr
+) {
+  return obsValuesForDaysIntervalArr.reduce(
     (accumulator, currentValue) => accumulator + currentValue
   );
 };
 
 /**
- * Calculate the sum of observation values within a time interval delimited by the start date and end date of a calendar month
- * @param {Array} obsArray An array of observations (timestamp + value) that is response from SensorThings API
- * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15 min", "60 min"
+ * Calculate the average (arithmetic mean) of observation values that fall within a time interval delimited by a start date and end date
+ * @param {Array} obsValuesForDaysIntervalArr An array of observation values that fall within our time interval
+ * @returns {Number} A floating-point number representing the average (arithmetic mean) of observation values
+ */
+const calculateAverageOfObservationValuesWithinDatesInterval = function (
+  obsValuesForDaysIntervalArr
+) {
+  return (
+    calculateSumOfObservationValuesWithinDatesInterval(
+      obsValuesForDaysIntervalArr
+    ) / obsValuesForDaysIntervalArr.length
+  );
+};
+
+/**
+ * Extract the year and month digits from a calendar month string
  * @param {String} calendarMonthStr Calendar month string in "YYYY-MM" format
- * @returns {Number} A floating-point number representing the sum of observation values
+ * @returns {Array} A 1*2 array tht contains integers representing the year and month respectively
  */
-const calculateSumOfObservationValuesWithinMonthInterval = function (
-  obsArray,
-  samplingRate,
+const extractMonthYearDigitsFromCalendarMonthString = function (
   calendarMonthStr
 ) {
   // Extract year as integer
@@ -146,6 +189,25 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
   // Extract month as integer
   const monthNum = parseInt(calendarMonthStr.slice(-2), 10);
 
+  return [yearNum, monthNum];
+};
+
+/**
+ * Extract the set of observation values that fall within a time interval delimited by the first day and last day of a calendar month
+ * @param {Array} obsArray An array of observations (timestamp + value) that is response from SensorThings API
+ * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15min", "60min"
+ * @param {String} calendarMonthStr Calendar month string in "YYYY-MM" format
+ * @returns {Array} An array of observation values that fall within one calendar month
+ */
+const extractObservationValuesWithinMonthInterval = function (
+  obsArray,
+  samplingRate,
+  calendarMonthStr
+) {
+  // Extract the year and month digits from the calendar month string
+  const [yearNum, monthNum] =
+    extractMonthYearDigitsFromCalendarMonthString(calendarMonthStr);
+
   if (monthNum < 1 || monthNum > 12) return;
 
   // All the months start on the first
@@ -155,7 +217,7 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
   if (monthNum === 2) {
     // Leap year
     if (checkIfLeapYear(yearNum))
-      return calculateSumOfObservationValuesWithinDatesInterval(
+      return extractObservationValuesWithinDatesInterval(
         obsArray,
         samplingRate,
         startDateStr,
@@ -163,7 +225,7 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
       );
 
     // Non-leap year
-    return calculateSumOfObservationValuesWithinDatesInterval(
+    return extractObservationValuesWithinDatesInterval(
       obsArray,
       samplingRate,
       startDateStr,
@@ -173,7 +235,7 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
 
   // Months with 30 days
   if (monthNum === 4 || monthNum === 6 || monthNum === 9 || monthNum === 11)
-    return calculateSumOfObservationValuesWithinDatesInterval(
+    return extractObservationValuesWithinDatesInterval(
       obsArray,
       samplingRate,
       startDateStr,
@@ -181,7 +243,7 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
     );
 
   // Months with 31 days
-  return calculateSumOfObservationValuesWithinDatesInterval(
+  return extractObservationValuesWithinDatesInterval(
     obsArray,
     samplingRate,
     startDateStr,
@@ -189,6 +251,130 @@ const calculateSumOfObservationValuesWithinMonthInterval = function (
   );
 };
 
+/**
+ * Calculate the sum of observation values that fall within a time interval delimited by the first day and last day of a calendar month
+ * @param {Array} obsValuesForMonthIntervalArr An array of observation values that fall within one calendar month
+ * @returns {Number} A floating-point number representing the sum of observation values within one calendar month
+ */
+const calculateSumOfObservationValuesWithinMonthInterval = function (
+  obsValuesForMonthIntervalArr
+) {
+  return obsValuesForMonthIntervalArr.reduce(
+    (accumulator, currentValue) => accumulator + currentValue
+  );
+};
+
+/**
+ * Calculate the average (arithmetic mean) of observation values that fall within a time interval delimited by the first day and last day of a calendar month
+ * @param {Array} obsValuesForMonthIntervalArr An array of observation values that fall within one calendar month
+ * @returns {Number} A floating-point number representing the average (arithmetic mean) of observation values within one calendar month
+ */
+const calculateAverageOfObservationValuesWithinMonthInterval = function (
+  obsValuesForMonthIntervalArr
+) {
+  return (
+    calculateSumOfObservationValuesWithinMonthInterval(
+      obsValuesForMonthIntervalArr
+    ) / obsValuesForMonthIntervalArr.length
+  );
+};
+
+/**
+ * Calculate the sum of observation values within a time interval delimited by a start date and end date. The time interval may be daily or monthly
+ * @param {Array} obsNestedArr A 1*N array that contains N nested arrays of observations (timestamp + value)
+ * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15min", "60min"
+ * @param {Array} uniqueCalendarDatesOrMonthsArr A 1*N array of unique calendar dates or calendar months strings
+ * @param {String} aggregationInterval The aggregation interval as a string e.g. "daily", "monthly"
+ * @returns {Array} A 1*N array that contains N nested arrays of sum values
+ */
+const calculateSumOfObservationValuesWithinInterval = function (
+  obsNestedArr,
+  samplingRate,
+  uniqueCalendarDatesOrMonthsArr,
+  aggregationInterval
+) {
+  // Calculate sum of values of observations - daily
+  // Note the use of the two nested `map` methods
+  if (aggregationInterval === "daily") {
+    return uniqueCalendarDatesOrMonthsArr.map((uniqueCalendarDatesArr, i) =>
+      uniqueCalendarDatesArr.map((uniqueCalendarDate) =>
+        calculateSumOfObservationValuesWithinDatesInterval(
+          extractObservationValuesWithinDatesInterval(
+            obsNestedArr[i],
+            samplingRate,
+            uniqueCalendarDate,
+            uniqueCalendarDate
+          )
+        )
+      )
+    );
+  }
+
+  // Calculate sum of values of observations - monthly
+  // Note the use of the two nested `map` methods
+  if (aggregationInterval === "monthly") {
+    return uniqueCalendarDatesOrMonthsArr.map((uniqueCalendarMonthsArr, i) =>
+      uniqueCalendarMonthsArr.map((uniqueCalendarMonth) =>
+        calculateSumOfObservationValuesWithinMonthInterval(
+          extractObservationValuesWithinMonthInterval(
+            obsNestedArr[i],
+            samplingRate,
+            uniqueCalendarMonth
+          )
+        )
+      )
+    );
+  }
+};
+
+/**
+ * Calculate the average (arithmetic mean) of observation values within a time interval delimited by a start date and end date. The time interval may be daily or monthly
+ * @param {Array} obsNestedArr A 1*N array that contains N nested arrays of observations (timestamp + value)
+ * @param {String} samplingRate The sampling rate of observations as a string, e.g. "15min", "60min"
+ * @param {Array} uniqueCalendarDatesOrMonthsArr A 1*N array of unique calendar dates or calendar months strings
+ * @param {String} aggregationInterval The aggregation interval as a string e.g. "daily", "monthly"
+ * @returns {Array} A 1*N array that contains N nested arrays of average (arithmetic mean) values
+ */
+const calculateAverageOfObservationValuesWithinInterval = function (
+  obsNestedArr,
+  samplingRate,
+  uniqueCalendarDatesOrMonthsArr,
+  aggregationInterval
+) {
+  // Calculate average of values of observations - daily
+  // Note the use of the two nested `map` methods
+  if (aggregationInterval === "daily") {
+    return uniqueCalendarDatesOrMonthsArr.map((uniqueCalendarDatesArr, i) =>
+      uniqueCalendarDatesArr.map((uniqueCalendarDate) =>
+        calculateAverageOfObservationValuesWithinDatesInterval(
+          extractObservationValuesWithinDatesInterval(
+            obsNestedArr[i],
+            samplingRate,
+            uniqueCalendarDate,
+            uniqueCalendarDate
+          )
+        )
+      )
+    );
+  }
+
+  // Calculate average of values of observations - monthly
+  // Note the use of the two nested `map` methods
+  if (aggregationInterval === "monthly") {
+    return uniqueCalendarDatesOrMonthsArr.map((uniqueCalendarMonthsArr, i) =>
+      uniqueCalendarMonthsArr.map((uniqueCalendarMonth) =>
+        calculateAverageOfObservationValuesWithinMonthInterval(
+          extractObservationValuesWithinMonthInterval(
+            obsNestedArr[i],
+            samplingRate,
+            uniqueCalendarMonth
+          )
+        )
+      )
+    );
+  }
+};
+
 /**
  * Extract unique calendar dates from date/time strings in ISO 8601 format
  * @param {Array} obsArray An array of observations (timestamp + value) that is response from SensorThings API
@@ -227,8 +413,8 @@ const extractUniqueCalendarMonthsFromCalendarDates = function (
 };
 
 export {
-  calculateSumOfObservationValuesWithinDatesInterval,
-  calculateSumOfObservationValuesWithinMonthInterval,
+  calculateSumOfObservationValuesWithinInterval,
   extractUniqueCalendarDatesFromTimestamp,
   extractUniqueCalendarMonthsFromCalendarDates,
+  calculateAverageOfObservationValuesWithinInterval,
 };

public/js/src_modules/calculateTemperatureDiff.mjs

+"use strict";
+
+import {
+  extractPhenomenonNameFromDatastreamName,
+  getMetadataPlusObservationsFromSingleOrMultipleDatastreams,
+} from "./fetchData.mjs";
+
+/**
+ * Calculate the temperature difference, dT, between Vorlauf temperature [VL] and Rücklauf temperature [RL] (i.e., dT = VL - RL)
+ * @param {String} baseUrl Base URL of the STA server
+ * @param {Object} urlParams The URL parameters to be sent together with the GET request
+ * @param {String} buildingId The building ID as a string
+ * @param {String} samplingRate The sampling rate as a string
+ * @returns {Promise} A promise that contains an array (that is made up of a temperature difference array and a metadata object) when fulfilled
+ */
+export const calculateVorlaufMinusRuecklaufTemperature = async function (
+  baseUrl,
+  urlParams,
+  buildingId,
+  samplingRate
+) {
+  try {
+    const bldgSensorSamplingRateNestedArr = [
+      [buildingId, "vl", samplingRate],
+      [buildingId, "rl", samplingRate],
+    ];
+
+    const BUILDING_ID = buildingId;
+    const SAMPLING_RATE = samplingRate;
+
+    const observationsPlusMetadata =
+      await getMetadataPlusObservationsFromSingleOrMultipleDatastreams(
+        baseUrl,
+        urlParams,
+        bldgSensorSamplingRateNestedArr
+      );
+
+    // Extract Vorlauf temperature, Ruecklauf temperature and metadata
+    const [
+      [vorlaufTemperatureObsArr, ruecklaufTemperatureObsArr],
+      [metadataVorlauf, metadataRuecklauf],
+    ] = observationsPlusMetadata;
+
+    // Extract the temperature values
+    const vorlaufTemperatureValues = vorlaufTemperatureObsArr.map(
+      (vlTempObs) => vlTempObs[1]
+    );
+    const ruecklaufTemperatureValues = ruecklaufTemperatureObsArr.map(
+      (rlTempObs) => rlTempObs[1]
+    );
+
+    // The arrays have equal length, we need only use one of them for looping
+    // Resulting array contains the following pairs (timestamp + dT)
+    const vorlaufMinusRuecklaufTemperatureObs = vorlaufTemperatureObsArr.map(
+      (vlTempObs, i) => [
+        vlTempObs[0], // timestamp
+        vorlaufTemperatureValues[i] - ruecklaufTemperatureValues[i],
+      ]
+    );
+
+    // From Vorlauf metadata, extract `name` and `unitOfMeasurement`
+    const {
+      name: datastreamNameVorlauf,
+      unitOfMeasurement: unitOfMeasurementVorlauf,
+    } = metadataVorlauf;
+
+    // From Ruecklauf metadata, extract `name`
+    const { name: datastreamNameRuecklauf } = metadataRuecklauf;
+
+    // Extract the phenomenon names from the Datastream names
+    const phenomenonNameVorlauf = extractPhenomenonNameFromDatastreamName(
+      datastreamNameVorlauf
+    );
+    const phenomenonNameRuecklauf = extractPhenomenonNameFromDatastreamName(
+      datastreamNameRuecklauf
+    );
+
+    // Create our custom datastream description text
+    // The resulting datastream description string has two `temperature` substrings;
+    // replace the first occurence with an empty string
+    const descriptionTempDifference =
+      `Computed dT: ${phenomenonNameVorlauf} minus ${phenomenonNameRuecklauf}`.replace(
+        "temperature",
+        ""
+      );
+
+    // Create our custom datastream name text
+    const nameTempDifference = `BOSCH_${BUILDING_ID} / dT Temperature difference (VL-RL) DS:${SAMPLING_RATE}`;
+
+    // The datastream object that we return needs to have these property names
+    const description = descriptionTempDifference;
+    const name = nameTempDifference;
+    const unitOfMeasurement = unitOfMeasurementVorlauf;
+
+    return [
+      vorlaufMinusRuecklaufTemperatureObs,
+      {
+        description,
+        name,
+        unitOfMeasurement,
+      },
+    ];
+  } catch (err) {
+    console.error(err);
+  }
+};

public/js/src_modules/chartColumn.mjs

+"use strict";
+
+import { chartExportOptions } from "./chartExport.mjs";
+
 /**
  * Format a computed aggregation result to make it suitable for a column chart
  * @param {Array} calendarDatesMonthsStrArr An array of unique calendar dates strings (in "YYYY-MM-DD" fromat) or unique calendar months strings (in "YYYY-MM" format)
@@ -123,6 +127,8 @@ const drawColumnChartHighcharts = function (
       },
     },
 
+    exporting: chartExportOptions,
+
     series: seriesOptionsArr,
   });
 };

public/js/src_modules/chartExport.mjs

+"use strict";
+
+export const chartExportOptions = {
+  buttons: {
+    contextButton: {
+      menuItems: ["downloadPNG", "downloadJPEG", "downloadPDF", "downloadSVG"],
+    },
+  },
+};