Apply Metrics::isLowerValueBetter to forecast values

Author: mneudert

plugins/CoreVisualizations/JqplotDataGenerator/Evolution.php

@@ -81,6 +81,7 @@ protected function initChartObjectData($dataTable, $visualization)
         // collect series data to show. each row-to-display/column-to-display permutation creates a series.
         $allSeriesData = [];
         $allSeriesDataAvailability = [];
+        $allSeriesAllowsDownwardForecast = [];
         foreach ($rowsToDisplay as $rowIdentifier) {
             $rowLabel = $rowIdentifier;
 
@@ -93,10 +94,32 @@ protected function initChartObjectData($dataTable, $visualization)
             }
 
             foreach ($columnsToDisplay as $columnName) {
+                $columnAllowsDownwardForecast = $this->columnAllowsDownwardForecast(
+                    $columnName,
+                    $units[$columnName] ?? false
+                );
+
                 if (!$this->isComparing) {
-                    $this->setNonComparisonSeriesData($allSeriesData, $allSeriesDataAvailability, $rowLabel, $columnName, $dataTable);
+                    $this->setNonComparisonSeriesData(
+                        $allSeriesData,
+                        $allSeriesDataAvailability,
+                        $allSeriesAllowsDownwardForecast,
+                        $rowLabel,
+                        $columnName,
+                        $columnAllowsDownwardForecast,
+                        $dataTable
+                    );
                 } else {
-                    $this->setComparisonSeriesData($allSeriesData, $allSeriesDataAvailability, $seriesLabels, $rowLabel, $columnName, $dataTable);
+                    $this->setComparisonSeriesData(
+                        $allSeriesData,
+                        $allSeriesDataAvailability,
+                        $allSeriesAllowsDownwardForecast,
+                        $seriesLabels,
+                        $rowLabel,
+                        $columnName,
+                        $columnAllowsDownwardForecast,
+                        $dataTable
+                    );
                 }
             }
         }
@@ -144,7 +167,14 @@ protected function initChartObjectData($dataTable, $visualization)
 
         $dataStates = $this->setDataStates($visualization, $dataTables);
         $visualization->setForecastData(
-            $this->buildForecastData($allSeriesData, $dataTables, $dataStates, $seriesUnits, $allSeriesDataAvailability)
+            $this->buildForecastData(
+                $allSeriesData,
+                $dataTables,
+                $dataStates,
+                $seriesUnits,
+                $allSeriesDataAvailability,
+                $allSeriesAllowsDownwardForecast
+            )
         );
     }
 
@@ -154,14 +184,16 @@ protected function initChartObjectData($dataTable, $visualization)
      * @param array<int, string> $dataStates
      * @param array<string, string|false> $seriesUnits
      * @param array<string, array<int, bool>> $allSeriesDataAvailability
+     * @param array<string, bool> $allSeriesAllowsDownwardForecast
      * @return array<int, array<int, float|null>>
      */
     protected function buildForecastData(
         array $allSeriesData,
         array $dataTables,
         array $dataStates,
         array $seriesUnits,
-        array $allSeriesDataAvailability
+        array $allSeriesDataAvailability,
+        array $allSeriesAllowsDownwardForecast
     ): array {
         if (empty($this->properties['show_forecast']) || $this->isComparing) {
             return [];
@@ -176,7 +208,33 @@ protected function buildForecastData(
             }
         }
 
-        return (new ForecastBuilder())->build($allSeriesData, $dataTables, $dataStates, $seriesUnits, $allSeriesDataAvailability);
+        return (new ForecastBuilder())->build(
+            $allSeriesData,
+            $dataTables,
+            $dataStates,
+            $seriesUnits,
+            $allSeriesDataAvailability,
+            $allSeriesAllowsDownwardForecast
+        );
+    }
+
+    /**
+     * Whether forecasts for a given column may legitimately fall below the current partial value.
+     *
+     * Counts (visits, conversions, etc.) only grow within an incomplete period, so their forecast
+     * is gated by the "forecast >= current" rule. Ratios and lower-is-better metrics (bounce rate,
+     * exit rate, average page generation time, position) can move either way during the period
+     * and need the gate lifted, otherwise valid downward trends are silently suppressed.
+     *
+     * @param string|false $columnUnit
+     */
+    private function columnAllowsDownwardForecast(string $columnName, $columnUnit): bool
+    {
+        if ($columnUnit === '%') {
+            return true;
+        }
+
+        return Metrics::isLowerValueBetter($columnName);
     }
 
     private function getSeriesData($rowLabel, $columnName, DataTable\Map $dataTable, &$seriesDataAvailability)
@@ -295,17 +353,33 @@ protected function addSelectedSeriesXLabels(array &$xLabels, array $dataTables)
         }
     }
 
-    private function setNonComparisonSeriesData(array &$allSeriesData, array &$allSeriesDataAvailability, $rowLabel, $columnName, DataTable\Map $dataTable)
-    {
+    private function setNonComparisonSeriesData(
+        array &$allSeriesData,
+        array &$allSeriesDataAvailability,
+        array &$allSeriesAllowsDownwardForecast,
+        $rowLabel,
+        $columnName,
+        bool $columnAllowsDownwardForecast,
+        DataTable\Map $dataTable
+    ) {
         $seriesLabel = $this->getSeriesLabel($rowLabel, $columnName);
 
         $seriesData = $this->getSeriesData($rowLabel, $columnName, $dataTable, $seriesDataAvailability);
         $allSeriesData[$seriesLabel] = $seriesData;
         $allSeriesDataAvailability[$seriesLabel] = $seriesDataAvailability;
+        $allSeriesAllowsDownwardForecast[$seriesLabel] = $columnAllowsDownwardForecast;
     }
 
-    private function setComparisonSeriesData(array &$allSeriesData, array &$allSeriesDataAvailability, array $seriesLabels, $rowLabel, $columnName, DataTable\Map $dataTable)
-    {
+    private function setComparisonSeriesData(
+        array &$allSeriesData,
+        array &$allSeriesDataAvailability,
+        array &$allSeriesAllowsDownwardForecast,
+        array $seriesLabels,
+        $rowLabel,
+        $columnName,
+        bool $columnAllowsDownwardForecast,
+        DataTable\Map $dataTable
+    ) {
         foreach ($dataTable->getDataTables() as $label => $childTable) {
             // get the row for this label (use the first if $rowLabel is false)
             if ($rowLabel === false) {
@@ -322,6 +396,7 @@ private function setComparisonSeriesData(array &$allSeriesData, array &$allSerie
                     $wholeSeriesLabel = $this->getComparisonSeriesLabelFromCompareSeries($seriesLabelPrefix, $columnName, $rowLabel);
                     $allSeriesData[$wholeSeriesLabel][] = 0;
                     $allSeriesDataAvailability[$wholeSeriesLabel][] = false;
+                    $allSeriesAllowsDownwardForecast[$wholeSeriesLabel] = $columnAllowsDownwardForecast;
                 }
 
                 continue;
@@ -334,6 +409,7 @@ private function setComparisonSeriesData(array &$allSeriesData, array &$allSerie
                 $value = $compareRow->getColumn($columnName);
                 $allSeriesData[$seriesLabel][] = $value;
                 $allSeriesDataAvailability[$seriesLabel][] = $this->hasColumnValue($value);
+                $allSeriesAllowsDownwardForecast[$seriesLabel] = $columnAllowsDownwardForecast;
             }
 
             $totalsRow = $comparisonTable->getTotalsRow();
@@ -342,6 +418,7 @@ private function setComparisonSeriesData(array &$allSeriesData, array &$allSerie
                 $value = $totalsRow->getColumn($columnName);
                 $allSeriesData[$seriesLabel][] = $value;
                 $allSeriesDataAvailability[$seriesLabel][] = $this->hasColumnValue($value);
+                $allSeriesAllowsDownwardForecast[$seriesLabel] = $columnAllowsDownwardForecast;
             }
         }
     }
@@ -487,6 +564,7 @@ public function precomputeForecast($dataTable): array
 
         $allSeriesData = [];
         $allSeriesDataAvailability = [];
+        $allSeriesAllowsDownwardForecast = [];
         foreach ($rowsToDisplay as $rowIdentifier) {
             $rowLabel = $rowIdentifier;
 
@@ -499,7 +577,20 @@ public function precomputeForecast($dataTable): array
             }
 
             foreach ($columnsToDisplay as $columnName) {
-                $this->setNonComparisonSeriesData($allSeriesData, $allSeriesDataAvailability, $rowLabel, $columnName, $dataTable);
+                $columnAllowsDownwardForecast = $this->columnAllowsDownwardForecast(
+                    $columnName,
+                    $units[$columnName] ?? false
+                );
+
+                $this->setNonComparisonSeriesData(
+                    $allSeriesData,
+                    $allSeriesDataAvailability,
+                    $allSeriesAllowsDownwardForecast,
+                    $rowLabel,
+                    $columnName,
+                    $columnAllowsDownwardForecast,
+                    $dataTable
+                );
             }
         }
 
@@ -508,7 +599,8 @@ public function precomputeForecast($dataTable): array
             $dataTables,
             $dataStates,
             $seriesUnits,
-            $allSeriesDataAvailability
+            $allSeriesDataAvailability,
+            $allSeriesAllowsDownwardForecast
         );
     }
 }