feat: add a forecasting task that takes exogenous variables

ForecastingTask offers a model the date and nothing else, so a series
that is driven by something measurable, a price, a promotion, the
temperature, could only be forecast from its own history.

ExogenousForecastingTask takes the same date column with one or more
numeric variables beside it, which the per-group column contract can now
express. It is a separate task rather than a wider ForecastingTask so
that each stays honest about what it offers: a model reading only a date
would silently drop the variables the user selected, and a model needing
them cannot be fitted without them.

What the two share, sorting the rows by date and reporting no labels,
moves to TimeSeriesTask. The date column is now found by type rather
than by position, since with variables alongside it need not come first.

The temporal splitters, the forecasting evaluation strategies, the
regression metrics and the Optuna optimizer serve the new task too.

Author: Irozuku

DashAI/back/evaluation/forecasting_cv.py

@@ -21,5 +21,5 @@ class ForecastingCrossValidationEvaluationStrategy(FoldEvaluationStrategy):
     origin forward through time.
     """
 
-    COMPATIBLE_COMPONENTS = ["ForecastingTask"]
+    COMPATIBLE_COMPONENTS = ["ForecastingTask", "ExogenousForecastingTask"]
     SCORED_SPLITS: tuple = (SplitEnum.VALIDATION, SplitEnum.TEST)

DashAI/back/evaluation/forecasting_holdout.py

@@ -44,5 +44,5 @@ class ForecastingHoldoutEvaluationStrategy(SinglePartitionEvaluationStrategy):
     they must not be fitted on it.
     """
 
-    COMPATIBLE_COMPONENTS = ["ForecastingTask"]
+    COMPATIBLE_COMPONENTS = ["ForecastingTask", "ExogenousForecastingTask"]
     SCORED_SPLITS: tuple = (SplitEnum.VALIDATION, SplitEnum.TEST)

DashAI/back/initial_components.py

@@ -459,6 +459,9 @@
     WilcoxonSRTest,
 )
 from DashAI.back.tasks.controlnet_task import ControlNetTask
+from DashAI.back.tasks.exogenous_forecasting_task import (
+    ExogenousForecastingTask,
+)
 from DashAI.back.tasks.forecasting_task import ForecastingTask
 from DashAI.back.tasks.image_classification_task import ImageClassificationTask
 
@@ -493,6 +496,7 @@ def get_initial_components():
         TranslationTask,
         RegressionTask,
         ForecastingTask,
+        ExogenousForecastingTask,
         NaiveForecaster,
         SeasonalNaiveForecaster,
         ARIMA,

DashAI/back/metrics/regression_metric.py

@@ -25,7 +25,11 @@ class RegressionMetric(BaseMetric):
     # ForecastingTask measures the same thing: a continuous prediction against
     # a continuous truth. Listing it here is what makes MAE, RMSE and the rest
     # available to forecasting runs without reimplementing any of them.
-    COMPATIBLE_COMPONENTS = ["RegressionTask", "ForecastingTask"]
+    COMPATIBLE_COMPONENTS = [
+        "RegressionTask",
+        "ForecastingTask",
+        "ExogenousForecastingTask",
+    ]
 
 
 def prepare_to_metric(

DashAI/back/optimizers/optuna_optimizer.py

@@ -225,6 +225,7 @@ class OptunaOptimizer(BaseOptimizer):
         "TranslationTask",
         "RegressionTask",
         "ForecastingTask",
+        "ExogenousForecastingTask",
     ]
 
     def __init__(self, n_trials=None, sampler=None, pruner=None):

DashAI/back/splitters/rolling_origin.py

@@ -151,7 +151,7 @@ class RollingOriginSplitter(FoldSplitter):
 
     SCHEMA = RollingOriginSplitterSchema
     TEST_SPLIT_STRATEGY: str = "temporal"
-    COMPATIBLE_COMPONENTS = ["ForecastingTask"]
+    COMPATIBLE_COMPONENTS = ["ForecastingTask", "ExogenousForecastingTask"]
     COMPATIBLE_INNER_SPLITTERS = ["RollingOriginSplitter"]
     DISPLAY_NAME: str = MultilingualString(
         en="Rolling Origin",

DashAI/back/splitters/temporal_holdout.py

@@ -131,7 +131,7 @@ class TemporalHoldoutSplitter(PartitionSplitter):
     """
 
     SCHEMA = TemporalHoldoutSplitterSchema
-    COMPATIBLE_COMPONENTS = ["ForecastingTask"]
+    COMPATIBLE_COMPONENTS = ["ForecastingTask", "ExogenousForecastingTask"]
     DISPLAY_NAME: str = MultilingualString(
         en="Temporal Holdout",
         es="Holdout Temporal",
@@ -150,9 +150,6 @@ def __init__(self, splits_data):
             proportions, and optionally previously computed indexes.
         """
         super().__init__(splits_data)
-        # The base class defaults these to values that would reintroduce
-        # randomness, and the schema does not expose either, so they are
-        # pinned here rather than trusted to arrive absent.
         self.shuffle = False
         self.stratify = False
 

DashAI/back/tasks/exogenous_forecasting_task.py

@@ -0,0 +1,71 @@
+from DashAI.back.core.utils import MultilingualString
+from DashAI.back.tasks.time_series_task import TimeSeriesTask
+from DashAI.back.types.value_types import Date, Float, Integer
+
+
+class ExogenousForecastingTask(TimeSeriesTask):
+    """Task for forecasting a time series with explanatory variables beside it.
+
+    The input is one ``Date`` column and at least one numeric column, and the
+    output is one numeric column: the series to forecast. The extra numeric
+    columns are the exogenous variables, the things measured alongside the
+    series that are believed to move it. Price and a promotion flag against
+    units sold, temperature against electricity demand, an advertising budget
+    against enquiries.
+
+    Splitting this off from :class:`ForecastingTask` rather than widening it is
+    what keeps each task honest about what it offers. A model that reads only
+    a date cannot use a price column, so offering it here would silently drop
+    the variables the user selected, and a model that needs explanatory
+    variables cannot be fitted without them.
+
+    Forecasting with exogenous variables asks something of the data that
+    forecasting from history alone does not: the variables have to be known
+    for the periods being forecast. That is what makes the approach worth the
+    trouble for a planned price or a published calendar, and what makes it a
+    poor fit for anything that would itself have to be forecast first.
+    """
+
+    DESCRIPTION: str = MultilingualString(
+        en=(
+            "Predict the future values of a time series using explanatory "
+            "variables measured alongside it. Takes one date column, one or "
+            "more numeric variables, and the numeric series to forecast."
+        ),
+        es=(
+            "Predice los valores futuros de una serie temporal usando "
+            "variables explicativas medidas junto a ella. Toma una columna de "
+            "fecha, una o mas variables numericas y la serie numerica a "
+            "pronosticar."
+        ),
+        pt=(
+            "Preve os valores futuros de uma serie temporal usando variaveis "
+            "explicativas medidas ao lado dela. Recebe uma coluna de data, uma "
+            "ou mais variaveis numericas e a serie numerica a prever."
+        ),
+        de=(
+            "Sagt die zukuenftigen Werte einer Zeitreihe mithilfe erklaerender "
+            "Variablen voraus, die daneben gemessen werden. Nimmt eine "
+            "Datumsspalte, eine oder mehrere numerische Variablen und die zu "
+            "prognostizierende numerische Reihe."
+        ),
+        zh=(
+            "利用与时间序列一同测量的解释变量预测其未来值。"
+            "接受一个日期列、一个或多个数值变量，以及要预测的数值序列。"
+        ),
+    )
+    DISPLAY_NAME: str = MultilingualString(
+        en="Forecasting with Exogenous Variables",
+        es="Pronostico con Variables Exogenas",
+        pt="Previsao com Variaveis Exogenas",
+        de="Zeitreihenprognose mit exogenen Variablen",
+        zh="含外生变量的时间序列预测",
+    )
+
+    metadata: dict = {
+        "inputs": [
+            {"types": [Date], "cardinality": 1},
+            {"types": [Float, Integer], "cardinality": {"min": 1, "max": "n"}},
+        ],
+        "outputs": [{"types": [Float, Integer], "cardinality": 1}],
+    }

DashAI/back/tasks/forecasting_task.py

@@ -1,17 +1,9 @@
-from typing import TYPE_CHECKING, List, Union
-
 from DashAI.back.core.utils import MultilingualString
-from DashAI.back.tasks.base_task import BaseTask
+from DashAI.back.tasks.time_series_task import TimeSeriesTask
 from DashAI.back.types.value_types import Date, Float, Integer
 
-if TYPE_CHECKING:
-    from datasets import DatasetDict
-    from numpy import ndarray
-
-    from DashAI.back.dataloaders.classes.dashai_dataset import DashAIDataset
-
 
-class ForecastingTask(BaseTask):
+class ForecastingTask(TimeSeriesTask):
     """Task for predicting the future values of a single time series.
 
     The input is one ``Date`` column and the output is one numeric column: the
@@ -20,7 +12,9 @@ class ForecastingTask(BaseTask):
 
     That restriction is the point. Models that take a date and nothing more,
     such as ARIMA or exponential smoothing, are a different family from models
-    that also take explanatory variables.
+    that also take explanatory variables. Those belong to
+    :class:`ExogenousForecastingTask`, which takes the same date column with
+    any number of numeric variables beside it.
 
     Two routes lead to a forecast in DashAI, and this is only one of them. The
     other is ``TimeSeriesWindowConverter``, which reshapes the same data into
@@ -29,8 +23,6 @@ class ForecastingTask(BaseTask):
     directly and cannot be expressed that way.
     """
 
-    PREDICTS_FORWARD_ONLY: bool = True
-
     DESCRIPTION: str = MultilingualString(
         en=(
             "Predict the future values of a time series from its own history. "
@@ -66,121 +58,6 @@ class ForecastingTask(BaseTask):
     )
 
     metadata: dict = {
-        "inputs_types": [Date],
-        "outputs_types": [Float, Integer],
-        "inputs_cardinality": 1,
-        "outputs_cardinality": 1,
+        "inputs": [{"types": [Date], "cardinality": 1}],
+        "outputs": [{"types": [Float, Integer], "cardinality": 1}],
     }
-
-    def prepare_for_task(
-        self,
-        dataset: Union["DatasetDict", "DashAIDataset"],
-        input_columns: List[str],
-        output_columns: List[str],
-    ) -> "DashAIDataset":
-        """Convert the dataset to a DashAIDataset and validate its types.
-
-        Parameters
-        ----------
-        dataset : DatasetDict or DashAIDataset
-            Dataset to prepare.
-        input_columns : list of str
-            The single date column.
-        output_columns : list of str
-            The single numeric column holding the series.
-
-        Returns
-        -------
-        DashAIDataset
-            Dataset with validated types, in date order.
-        """
-        prepared = super().prepare_for_task(dataset, input_columns, output_columns)
-        return self._sort_by_date(prepared, input_columns[0])
-
-    @staticmethod
-    def _sort_by_date(dataset: "DashAIDataset", date_column: str) -> "DashAIDataset":
-        """Put the rows in date order.
-
-        Everything downstream reads row order as time order and none of it
-        checks: the temporal splitter carves its partitions by position, and
-        the models hand their values to statsmodels in the order they arrive.
-        A file that is not sorted by its date column therefore produces
-        partitions that are not periods of time and a model fitted on a
-        scrambled series, with nothing reporting a problem.
-
-        This is the task's job rather than the splitter's. The splitter is
-        handed the selected input columns, which on the windowed route through
-        ``TimeSeriesWindowConverter`` are lag columns with no date among them.
-
-        Sorting reads the format the column declares. Text order only matches
-        time order for ISO layouts: as text, "01/02/2020" precedes
-        "31/01/2020" while following it in time.
-
-        Parameters
-        ----------
-        dataset : DashAIDataset
-            The validated dataset.
-        date_column : str
-            The single input column, which the task has already checked is a
-            ``Date``.
-
-        Returns
-        -------
-        DashAIDataset
-            The same rows and types, ordered by date.
-        """
-        from DashAI.back.dataloaders.classes.dashai_dataset import to_dashai_dataset
-        from DashAI.back.types.date_utils import DEFAULT_DATE_FORMAT, parse_date_column
-
-        date_format = (
-            getattr(dataset.types[date_column], "format", None) or DEFAULT_DATE_FORMAT
-        )
-        frame = dataset.to_pandas()
-        order = parse_date_column(frame[date_column], date_format).sort_values().index
-
-        if list(order) == list(frame.index):
-            return dataset
-
-        return to_dashai_dataset(
-            frame.loc[order].reset_index(drop=True), types=dict(dataset.types)
-        )
-
-    def process_predictions(
-        self, dataset: "DashAIDataset", predictions: "ndarray", output_column: str
-    ):
-        """Return the forecast values unchanged.
-
-        Parameters
-        ----------
-        dataset : DashAIDataset
-            Dataset used for training.
-        predictions : np.ndarray
-            Predictions from the model.
-        output_column : str
-            Output column.
-
-        Returns
-        -------
-        np.ndarray
-            The predictions as they were produced. A forecast is already a
-            number on the scale of the series, so there is nothing to decode.
-        """
-        return predictions
-
-    def num_labels(self, dataset: "DashAIDataset", output_column: str) -> int | None:
-        """Report that this task has no labels.
-
-        Parameters
-        ----------
-        dataset : DashAIDataset
-            Dataset used for training.
-        output_column : str
-            Output column.
-
-        Returns
-        -------
-        int | None
-            Always ``None``: the output is continuous, so there is no class
-            count for a model to size itself against.
-        """
-        return None