fix: count forecast steps on the calendar grid, not in days

_steps_ahead measured the distance to a requested date in days and divided
by the typical gap between training rows. A calendar period is not a fixed
number of days: months run 28 to 31, the median lands on 31, and the count
falls a whole period behind after roughly two years.

On a monthly series with a five year horizon, 34 of 60 rows came out one
step short. Two different months then collapsed onto the same forecast and
the last real period was never scored, so a seasonal naive forecaster with
the right season length got 34 of 60 predictions wrong on a perfectly
seasonal series.

When the training rows sit on a regular grid, infer_frequency names it and a
position on that grid is exact however long the horizon gets. The day count
stays as the fallback for irregular series, where no step is well defined
anyway, so their behaviour is unchanged.

Author: cristian-tamblay

DashAI/back/models/forecasting/base_forecasting_model.py

@@ -6,6 +6,7 @@
 
 if TYPE_CHECKING:
     import numpy as np
+    import pandas as pd
 
     from DashAI.back.dataloaders.classes.dashai_dataset import DashAIDataset
 
@@ -45,6 +46,7 @@ def __init__(self, **kwargs):
         # is what lets predict turn a date into a number of steps ahead.
         self._last_train_date = None
         self._step_delta = None
+        self._freq_alias = None
         self._date_format = None
 
     @staticmethod
@@ -90,7 +92,11 @@ def _remember_dates(self, x_train: "DashAIDataset") -> None:
         x_train : DashAIDataset
             The training input, holding the date column.
         """
-        from DashAI.back.types.date_utils import DEFAULT_DATE_FORMAT, parse_date_column
+        from DashAI.back.types.date_utils import (
+            DEFAULT_DATE_FORMAT,
+            infer_frequency,
+            parse_date_column,
+        )
         from DashAI.back.types.value_types import Date
 
         date_columns = [
@@ -102,6 +108,7 @@ def _remember_dates(self, x_train: "DashAIDataset") -> None:
             # Nothing to align against; predict falls back to counting rows.
             self._last_train_date = None
             self._step_delta = None
+            self._freq_alias = None
             return
 
         self._date_format = (
@@ -120,6 +127,54 @@ def _remember_dates(self, x_train: "DashAIDataset") -> None:
         if self._step_delta is not None and self._step_delta.total_seconds() <= 0:
             self._step_delta = None
 
+        # A calendar period is not a fixed number of days, so measuring in
+        # days drifts: months run 28 to 31, the median lands on 31, and after
+        # a couple of years the count is a whole period short. When the rows
+        # sit on a regular grid the alias names that grid, and a position on
+        # it is exact however long the horizon gets.
+        alias = infer_frequency(dates)
+        self._freq_alias = alias if isinstance(alias, str) else None
+
+    def _steps_from_grid(self, dates: "pd.Series") -> "np.ndarray | None":
+        """Read each date as a position on the calendar grid of the training rows.
+
+        Counting positions rather than dividing durations is what keeps a
+        monthly or quarterly series aligned: those periods are not a fixed
+        number of days, so a duration divided by the typical gap drifts by a
+        whole period over a long enough horizon.
+
+        Parameters
+        ----------
+        dates : pd.Series
+            The requested dates, already parsed.
+
+        Returns
+        -------
+        np.ndarray or None
+            One step number per date, or ``None`` when the grid cannot answer:
+            no regular frequency, a missing date, or a date that does not land
+            on the grid. The caller then measures by duration instead.
+        """
+        import pandas as pd
+
+        if self._freq_alias is None or dates.isna().any():
+            return None
+
+        grid = pd.date_range(
+            start=self._last_train_date, end=dates.max(), freq=self._freq_alias
+        )
+        # The grid starts at the last training date, so a position on it is
+        # already a number of steps past the end of training. date_range rolls
+        # a start that is off the grid forward, which would break that.
+        if len(grid) == 0 or grid[0] != self._last_train_date:
+            return None
+
+        positions = grid.get_indexer(pd.DatetimeIndex(dates))
+        if (positions < 0).any():
+            return None
+
+        return positions
+
     def _steps_ahead(self, x: "DashAIDataset") -> "np.ndarray":
         """Work out how many periods past training each requested date falls.
 
@@ -158,8 +213,13 @@ def _steps_ahead(self, x: "DashAIDataset") -> "np.ndarray":
             return np.arange(1, len(x) + 1)
 
         dates = parse_date_column(x.to_pandas()[date_columns[0]], self._date_format)
-        offsets = (dates - self._last_train_date) / self._step_delta
-        steps = np.rint(offsets.to_numpy(dtype=float)).astype(int)
+
+        steps = self._steps_from_grid(dates)
+        if steps is None:
+            # No regular grid to count on, so the best available reading is
+            # how many typical gaps each date lies past the end of training.
+            offsets = (dates - self._last_train_date) / self._step_delta
+            steps = np.rint(offsets.to_numpy(dtype=float)).astype(int)
 
         if (steps < 1).any():
             raise ValueError(

tests/back/models/test_forecasting_horizon.py

@@ -49,6 +49,14 @@ def _actual(y_split):
     return np.asarray(y_split.to_pandas().iloc[:, 0], dtype=float)
 
 
+def _rows(dataset, start, stop):
+    """A contiguous slice of a dataset, keeping its column types."""
+    return to_dashai_dataset(
+        dataset.to_pandas().iloc[start:stop].reset_index(drop=True),
+        types=dict(dataset.types),
+    )
+
+
 def test_the_test_partition_is_forecast_at_its_own_dates():
     # The regression this file exists for. On a perfectly linear series ARIMA
     # should land on the test values; before the fix it returned the
@@ -129,3 +137,74 @@ def test_asking_for_a_date_inside_the_training_range_is_refused(model_class):
 
     with pytest.raises(ValueError, match="inside the training data"):
         model.predict(xs["train"])
+
+
+@pytest.mark.parametrize("freq", ["MS", "ME", "QS"])
+def test_a_calendar_series_stays_aligned_over_a_long_horizon(freq):
+    # A calendar period is not a fixed number of days. Reading the distance to
+    # a date in days and dividing by the typical gap drifts: months run 28 to
+    # 31, the median lands on 31, and after roughly two years the count is a
+    # whole period short. Two different months then collapse onto the same
+    # forecast and every later row is off by one.
+    xs, ys, _ = _split(n=180, freq=freq)
+    model = NaiveForecaster()
+    model.train(xs["train"], ys["train"])
+
+    steps = model._steps_ahead(xs["test"])
+
+    first = len(xs["validation"]) + 1
+    assert list(steps) == list(range(first, first + len(xs["test"])))
+
+
+def test_a_seasonal_monthly_series_is_forecast_exactly():
+    # The value level version of the same thing: a seasonal naive forecaster
+    # given the right season length on a perfectly seasonal series should get
+    # every month right, and the drift used to spoil more than half of them.
+    dates = pd.date_range("2016-01-01", periods=120, freq="MS").strftime("%Y-%m-%d")
+    series = [float(10 * (i % 12)) for i in range(120)]
+    dataset = transform_dataset_with_schema(
+        to_dashai_dataset(pd.DataFrame({"date": dates.tolist(), "v": series})),
+        {
+            "date": {"type": "Date", "dtype": "%Y-%m-%d"},
+            "v": {"type": "Float", "dtype": "float64"},
+        },
+    )
+    x, y = select_columns(dataset, ["date"], ["v"])
+    cut = 60
+
+    model = SeasonalNaiveForecaster(season_length=12)
+    model.train(_rows(x, 0, cut), _rows(y, 0, cut))
+
+    forecast = np.asarray(model.predict(_rows(x, cut, 120)), dtype=float)
+
+    assert forecast == pytest.approx(series[cut:])
+
+
+def test_an_irregular_series_still_forecasts_by_typical_gap():
+    # No regular grid to count positions on, so the reading falls back to how
+    # many typical gaps each date lies past the end of training. That is the
+    # best available answer rather than a refusal.
+    dates = [
+        "2026-01-01",
+        "2026-01-05",
+        "2026-01-06",
+        "2026-02-01",
+        "2026-02-15",
+        "2026-03-02",
+    ]
+    dataset = transform_dataset_with_schema(
+        to_dashai_dataset(
+            pd.DataFrame({"date": dates, "v": [float(i) for i in range(6)]})
+        ),
+        {
+            "date": {"type": "Date", "dtype": "%Y-%m-%d"},
+            "v": {"type": "Float", "dtype": "float64"},
+        },
+    )
+    x, y = select_columns(dataset, ["date"], ["v"])
+
+    model = NaiveForecaster()
+    model.train(_rows(x, 0, 4), _rows(y, 0, 4))
+
+    assert model._freq_alias is None
+    assert len(model.predict(_rows(x, 4, 6))) == 2