Use damped linear-trend prior for forecast historical samples

mneudert · mneudert · commit 74a48f37fcc4 · 2026-04-29T16:10:41.000+02:00
diff --git a/plugins/CoreVisualizations/JqplotDataGenerator/ForecastBuilder.php b/plugins/CoreVisualizations/JqplotDataGenerator/ForecastBuilder.php
@@ -37,6 +37,16 @@ class ForecastBuilder
 {
     private const MIN_FORECAST_RATIO = 0.05;
 
+    /**
+     * Damping factor applied to the linear-trend projection of the historical prior.
+     * 1.0 = full least-squares extrapolation (most responsive to trends, most prone to
+     * overshoot on noisy ratios). 0.0 = no projection (flat mean). 0.5 keeps the regression
+     * line's fit on the historical samples but only takes a half-step in the slope direction
+     * for the next-period forecast — empirically a good tradeoff between catching growth on
+     * count series and not amplifying noise on volatile averages.
+     */
+    private const TREND_DAMPING = 0.5;
+
     /**
      * @param array<string, array<int, float|int>> $allSeriesData
      * @param array<DataTable> $dataTables
@@ -156,7 +166,7 @@ public function build(
      * has no positive value so a synthetic 0 does not collapse the linear seed to zero. When the
      * current tick is the first incomplete tick (no previous forecast) and historical priors
      * exist, the blend would otherwise dilute the prior with a meaningless zero, so it falls back
-     * to the prior mean directly.
+     * to the prior directly. The prior itself is trend-aware via computeHistoricalPrior.
      *
      * @param array<int, float> $pastValues
      */
@@ -175,7 +185,7 @@ private function buildMonotonicForecastValue(
         $priorForecast = $linearForecast;
 
         if ([] !== $pastValues) {
-            $priorForecast = array_sum($pastValues) / count($pastValues);
+            $priorForecast = $this->computeHistoricalPrior($pastValues);
         }
 
         $weight = $this->getPriorForecastWeight(count($pastValues), $this->getPeriodLabel($dataTable));
@@ -197,15 +207,16 @@ private function buildMonotonicForecastValue(
 
     /**
      * Forecast for non-monotonic series (ratios, averages, latency-style). Returns the historical
-     * same-period prior, falling back to the previous forecast if there is no prior. Returns null
-     * when neither signal is available because no defensible value can be produced.
+     * same-period prior (trend-aware via computeHistoricalPrior), falling back to the previous
+     * forecast if there is no prior. Returns null when neither signal is available because no
+     * defensible value can be produced.
      *
      * @param array<int, float> $pastValues
      */
     private function buildNonMonotonicForecastValue(array $pastValues, ?float $previousForecastValue): ?float
     {
         if ([] !== $pastValues) {
-            return array_sum($pastValues) / count($pastValues);
+            return $this->computeHistoricalPrior($pastValues);
         }
 
         if ($previousForecastValue !== null) {
@@ -215,6 +226,50 @@ private function buildNonMonotonicForecastValue(array $pastValues, ?float $previ
         return null;
     }
 
+    /**
+     * Same-period historical prior used by both forecast paths. With fewer than two samples
+     * there is no slope to fit and the only signal is the single value (or a flat mean).
+     * With two or more samples we apply a least-squares linear-trend extrapolation projected
+     * one step forward, then dampen the projection by TREND_DAMPING so noisy ratios do not
+     * runaway-extrapolate from a spurious slope. Catching sustained growth or decline that a
+     * flat mean would systematically lag is the win; the damping is what keeps that win from
+     * becoming a loss on volatile averages. The result is clamped to >= 0 because every metric
+     * the builder serves (counts, percentages, durations) is non-negative; a negative trend
+     * extrapolation past zero is never a defensible forecast.
+     *
+     * @param array<int, float> $pastValues Same-period historical samples in temporal order
+     *        (oldest first), already filtered and stripped of leading zeros by the caller.
+     */
+    private function computeHistoricalPrior(array $pastValues): float
+    {
+        $sampleCount = count($pastValues);
+        if ($sampleCount < 2) {
+            return max(0.0, (float) $pastValues[0]);
+        }
+
+        $sumX = $sampleCount * ($sampleCount + 1) / 2;
+        $sumY = array_sum($pastValues);
+        $sumXX = 0.0;
+        $sumXY = 0.0;
+        for ($i = 0; $i < $sampleCount; ++$i) {
+            $x = $i + 1;
+            $sumXX += $x * $x;
+            $sumXY += $x * $pastValues[$i];
+        }
+
+        $denominator = $sampleCount * $sumXX - $sumX * $sumX;
+        if ($denominator <= 0.0) {
+            return max(0.0, $sumY / $sampleCount);
+        }
+
+        $slope = ($sampleCount * $sumXY - $sumX * $sumY) / $denominator;
+        $intercept = ($sumY - $slope * $sumX) / $sampleCount;
+
+        // Equivalent to projecting from the regressed value at x=sampleCount and taking a
+        // fractional step in the slope direction: y(n) + damping * slope.
+        return max(0.0, $intercept + $slope * ($sampleCount + self::TREND_DAMPING));
+    }
+
     /**
      * @param array<int, float|int> $seriesData
      * @param array<int, DataTable> $dataTableList
diff --git a/plugins/CoreVisualizations/tests/Unit/JqplotDataGenerator/ForecastBuilderTest.php b/plugins/CoreVisualizations/tests/Unit/JqplotDataGenerator/ForecastBuilderTest.php
@@ -289,15 +289,17 @@ public function testBuildReusesForecastAsSyntheticDataForLaterNoDataDaysAndRecal
         self::assertSame([[null, null, null, null, 47.9996, 58.3997, 74.7198, 59.9994]], $forecastData);
     }
 
-    public function testBuildMonotonicReturnsFullPriorWhenIncompleteTickHasNoData(): void
+    public function testBuildMonotonicReturnsTrendAwarePriorWhenIncompleteTickHasNoData(): void
     {
         $site = $this->createSiteMock();
 
         // The "today" tick exists in the date range but has no archived data yet — currentValue
         // is 0 and there is no earlier incomplete tick to carry a forecast forward from. The
         // blend would otherwise dilute the historical prior with a meaningless zero; the builder
-        // must return the full prior mean instead. Apr 3/10/17/24 are all Fridays so the daily
-        // weekday filter keeps every prior tick in the sample.
+        // falls back to computeHistoricalPrior. With three same-weekday priors [80, 100, 60] the
+        // least-squares fit gives slope = -10, intercept = 100. The damped projection at
+        // x = 3 + TREND_DAMPING (0.5) is 100 + (-10) * 3.5 = 65. Apr 3/10/17/24 are all Fridays
+        // so the daily weekday filter keeps every prior tick in the sample.
         $dataTables = [
             $this->createDataTableForDay('2026-04-03', $site),
             $this->createDataTableForDay('2026-04-10', $site),
@@ -317,7 +319,103 @@ public function testBuildMonotonicReturnsFullPriorWhenIncompleteTickHasNoData():
             ['Visits' => false]
         );
 
-        self::assertSame([[null, null, null, 80.0]], $forecastData);
+        self::assertSame([[null, null, null, 65.0]], $forecastData);
+    }
+
+    public function testBuildAppliesDampedLinearTrendOnMultiSamplePriors(): void
+    {
+        $site = $this->createSiteMock();
+
+        // Five consecutive Fridays so the daily weekday filter keeps all four priors. Priors
+        // [100, 120, 140, 160] form a clean linear trend: slope = 20, intercept = 80, regressed
+        // value at x=4 = 160. The damped projection adds TREND_DAMPING * slope to that anchor:
+        // 160 + 0.5 * 20 = 170. A flat-mean predictor would have returned 130, so the test pins
+        // the trend-aware behaviour on a realistic four-week history.
+        $dataTables = [
+            $this->createDataTableForDay('2026-04-03', $site),
+            $this->createDataTableForDay('2026-04-10', $site),
+            $this->createDataTableForDay('2026-04-17', $site),
+            $this->createDataTableForDay('2026-04-24', $site),
+            $this->createDataTableForDay('2026-05-01', $site, '2026-05-01 00:00:00'),
+        ];
+
+        $forecastData = (new ForecastBuilder())->build(
+            ['Visits' => [100.0, 120.0, 140.0, 160.0, 0.0]],
+            $dataTables,
+            [
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::INCOMPLETE,
+            ],
+            ['Visits' => false]
+        );
+
+        self::assertSame([[null, null, null, null, 170.0]], $forecastData);
+    }
+
+    public function testBuildPriorReducesToMeanWhenTrendIsFlat(): void
+    {
+        $site = $this->createSiteMock();
+
+        // With identical priors the least-squares slope is zero, so the damped projection
+        // reduces exactly to the historical mean. This guards against accidental drift the
+        // trend formulation might introduce on stable series.
+        $dataTables = [
+            $this->createDataTableForDay('2026-04-03', $site),
+            $this->createDataTableForDay('2026-04-10', $site),
+            $this->createDataTableForDay('2026-04-17', $site),
+            $this->createDataTableForDay('2026-04-24', $site),
+            $this->createDataTableForDay('2026-05-01', $site, '2026-05-01 00:00:00'),
+        ];
+
+        $forecastData = (new ForecastBuilder())->build(
+            ['Visits' => [50.0, 50.0, 50.0, 50.0, 0.0]],
+            $dataTables,
+            [
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::INCOMPLETE,
+            ],
+            ['Visits' => false]
+        );
+
+        self::assertSame([[null, null, null, null, 50.0]], $forecastData);
+    }
+
+    public function testBuildClampsNegativeTrendExtrapolationToZero(): void
+    {
+        $site = $this->createSiteMock();
+
+        // A steeply collapsing prior series produces a damped extrapolation below zero
+        // (slope = -32.5, intercept = 122.5, damped projection at x=4.5 = -23.75). Counts and
+        // percentages are non-negative by construction, so the forecast clamps to 0 rather
+        // than rendering a meaningless negative value on the chart.
+        $dataTables = [
+            $this->createDataTableForDay('2026-04-03', $site),
+            $this->createDataTableForDay('2026-04-10', $site),
+            $this->createDataTableForDay('2026-04-17', $site),
+            $this->createDataTableForDay('2026-04-24', $site),
+            $this->createDataTableForDay('2026-05-01', $site, '2026-05-01 00:00:00'),
+        ];
+
+        $forecastData = (new ForecastBuilder())->build(
+            ['Visits' => [100.0, 50.0, 10.0, 5.0, 0.0]],
+            $dataTables,
+            [
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::COMPLETE,
+                ArchiveState::INCOMPLETE,
+            ],
+            ['Visits' => false]
+        );
+
+        self::assertSame([[null, null, null, null, 0.0]], $forecastData);
     }
 
     public function testBuildDoesNotCarryForwardAcrossSuppressedForecastGap(): void
