autogluon.timeseries 1.2.1b20250224__py3-none-any.whl → 1.4.1b20251215__py3-none-any.whl

autogluon/timeseries/learner.py

@@ -1,18 +1,17 @@
 import logging
 import reprlib
 import time
-from typing import Any, Dict, List, Literal, Optional, Type, Union
+from typing import Any, Literal, Type
 
 import pandas as pd
 
 from autogluon.core.learner import AbstractLearner
-from autogluon.timeseries.dataset.ts_dataframe import TimeSeriesDataFrame
+from autogluon.timeseries.dataset import TimeSeriesDataFrame
 from autogluon.timeseries.metrics import TimeSeriesScorer, check_get_evaluation_metric
 from autogluon.timeseries.models.abstract import AbstractTimeSeriesModel
-from autogluon.timeseries.splitter import AbstractWindowSplitter
 from autogluon.timeseries.trainer import TimeSeriesTrainer
 from autogluon.timeseries.utils.features import TimeSeriesFeatureGenerator
-from autogluon.timeseries.utils.forecast import get_forecast_horizon_index_ts_dataframe
+from autogluon.timeseries.utils.forecast import make_future_data_frame
 
 logger = logging.getLogger(__name__)
 
@@ -26,25 +25,23 @@ class TimeSeriesLearner(AbstractLearner):
         self,
         path_context: str,
         target: str = "target",
-        known_covariates_names: Optional[List[str]] = None,
+        known_covariates_names: list[str] | None = None,
         trainer_type: Type[TimeSeriesTrainer] = TimeSeriesTrainer,
-        eval_metric: Union[str, TimeSeriesScorer, None] = None,
-        eval_metric_seasonal_period: Optional[int] = None,
+        eval_metric: str | TimeSeriesScorer | None = None,
         prediction_length: int = 1,
         cache_predictions: bool = True,
-        ensemble_model_type: Optional[Type] = None,
+        ensemble_model_type: Type | None = None,
         **kwargs,
     ):
         super().__init__(path_context=path_context)
-        self.eval_metric: TimeSeriesScorer = check_get_evaluation_metric(eval_metric)
-        self.eval_metric_seasonal_period = eval_metric_seasonal_period
+        self.eval_metric = check_get_evaluation_metric(eval_metric, prediction_length=prediction_length)
         self.trainer_type = trainer_type
         self.target = target
         self.known_covariates_names = [] if known_covariates_names is None else known_covariates_names
         self.prediction_length = prediction_length
         self.quantile_levels = kwargs.get("quantile_levels", [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9])
         self.cache_predictions = cache_predictions
-        self.freq: Optional[str] = None
+        self.freq: str | None = None
         self.ensemble_model_type = ensemble_model_type
 
         self.feature_generator = TimeSeriesFeatureGenerator(
@@ -58,13 +55,15 @@ class TimeSeriesLearner(AbstractLearner):
     def fit(
         self,
         train_data: TimeSeriesDataFrame,
-        hyperparameters: Union[str, Dict],
-        val_data: Optional[TimeSeriesDataFrame] = None,
-        hyperparameter_tune_kwargs: Optional[Union[str, dict]] = None,
-        time_limit: Optional[float] = None,
-        val_splitter: Optional[AbstractWindowSplitter] = None,
-        refit_every_n_windows: Optional[int] = 1,
-        random_seed: Optional[int] = None,
+        hyperparameters: str | dict,
+        val_data: TimeSeriesDataFrame | None = None,
+        hyperparameter_tune_kwargs: str | dict | None = None,
+        ensemble_hyperparameters: dict[str, Any] | list[dict[str, Any]] | None = None,
+        time_limit: float | None = None,
+        num_val_windows: tuple[int, ...] = (1,),
+        val_step_size: int | None = None,
+        refit_every_n_windows: int | None = 1,
+        random_seed: int | None = None,
         **kwargs,
     ) -> None:
         self._time_limit = time_limit
@@ -82,14 +81,14 @@ class TimeSeriesLearner(AbstractLearner):
                 path=self.model_context,
                 prediction_length=self.prediction_length,
                 eval_metric=self.eval_metric,
-                eval_metric_seasonal_period=self.eval_metric_seasonal_period,
                 target=self.target,
                 quantile_levels=self.quantile_levels,
                 verbosity=kwargs.get("verbosity", 2),
                 skip_model_selection=kwargs.get("skip_model_selection", False),
                 enable_ensemble=kwargs.get("enable_ensemble", True),
-                metadata=self.feature_generator.covariate_metadata,
-                val_splitter=val_splitter,
+                covariate_metadata=self.feature_generator.covariate_metadata,
+                num_val_windows=num_val_windows,
+                val_step_size=val_step_size,
                 refit_every_n_windows=refit_every_n_windows,
                 cache_predictions=self.cache_predictions,
                 ensemble_model_type=self.ensemble_model_type,
@@ -97,7 +96,7 @@ class TimeSeriesLearner(AbstractLearner):
         )
 
         assert issubclass(self.trainer_type, TimeSeriesTrainer)
-        self.trainer: Optional[TimeSeriesTrainer] = self.trainer_type(**trainer_init_kwargs)
+        self.trainer: TimeSeriesTrainer | None = self.trainer_type(**trainer_init_kwargs)
         self.trainer_path = self.trainer.path
         self.save()
 
@@ -114,6 +113,7 @@ class TimeSeriesLearner(AbstractLearner):
             val_data=val_data,
             hyperparameters=hyperparameters,
             hyperparameter_tune_kwargs=hyperparameter_tune_kwargs,
+            ensemble_hyperparameters=ensemble_hyperparameters,
             excluded_model_types=kwargs.get("excluded_model_types"),
             time_limit=time_limit,
             random_seed=random_seed,
@@ -124,9 +124,9 @@ class TimeSeriesLearner(AbstractLearner):
 
     def _align_covariates_with_forecast_index(
         self,
-        known_covariates: Optional[TimeSeriesDataFrame],
+        known_covariates: TimeSeriesDataFrame | None,
         data: TimeSeriesDataFrame,
-    ) -> Optional[TimeSeriesDataFrame]:
+    ) -> TimeSeriesDataFrame | None:
         """Select the relevant item_ids and timestamps from the known_covariates dataframe.
 
         If some of the item_ids or timestamps are missing, an exception is raised.
@@ -148,25 +148,27 @@ class TimeSeriesLearner(AbstractLearner):
                 f"known_covariates are missing information for the following item_ids: {reprlib.repr(missing_item_ids.to_list())}."
             )
 
-        forecast_index = get_forecast_horizon_index_ts_dataframe(
-            data, prediction_length=self.prediction_length, freq=self.freq
+        forecast_index = pd.MultiIndex.from_frame(
+            make_future_data_frame(data, prediction_length=self.prediction_length, freq=self.freq)
         )
         try:
             known_covariates = known_covariates.loc[forecast_index]  # type: ignore
         except KeyError:
             raise ValueError(
-                f"known_covariates should include the values for prediction_length={self.prediction_length} "
-                "many time steps into the future."
+                "`known_covariates` should include the `item_id` and `timestamp` values covering the forecast horizon "
+                "(i.e., the next `prediction_length` time steps following the end of each time series in the input "
+                "data). Use `TimeSeriesPredictor.make_future_data_frame` to generate the required `item_id` and "
+                "`timestamp` combinations for the `known_covariates`."
             )
         return known_covariates
 
     def predict(
         self,
         data: TimeSeriesDataFrame,
-        known_covariates: Optional[TimeSeriesDataFrame] = None,
-        model: Optional[Union[str, AbstractTimeSeriesModel]] = None,
+        known_covariates: TimeSeriesDataFrame | None = None,
+        model: str | AbstractTimeSeriesModel | None = None,
         use_cache: bool = True,
-        random_seed: Optional[int] = None,
+        random_seed: int | None = None,
         **kwargs,
     ) -> TimeSeriesDataFrame:
         data = self.feature_generator.transform(data)
@@ -184,8 +186,8 @@ class TimeSeriesLearner(AbstractLearner):
     def score(
         self,
         data: TimeSeriesDataFrame,
-        model: Optional[Union[str, AbstractTimeSeriesModel]] = None,
-        metric: Union[str, TimeSeriesScorer, None] = None,
+        model: str | AbstractTimeSeriesModel | None = None,
+        metric: str | TimeSeriesScorer | None = None,
         use_cache: bool = True,
     ) -> float:
         data = self.feature_generator.transform(data)
@@ -194,24 +196,24 @@ class TimeSeriesLearner(AbstractLearner):
     def evaluate(
         self,
         data: TimeSeriesDataFrame,
-        model: Optional[str] = None,
-        metrics: Optional[Union[str, TimeSeriesScorer, List[Union[str, TimeSeriesScorer]]]] = None,
+        model: str | None = None,
+        metrics: str | TimeSeriesScorer | list[str | TimeSeriesScorer] | None = None,
         use_cache: bool = True,
-    ) -> Dict[str, float]:
+    ) -> dict[str, float]:
         data = self.feature_generator.transform(data)
         return self.load_trainer().evaluate(data=data, model=model, metrics=metrics, use_cache=use_cache)
 
     def get_feature_importance(
         self,
-        data: Optional[TimeSeriesDataFrame] = None,
-        model: Optional[str] = None,
-        metric: Optional[Union[str, TimeSeriesScorer]] = None,
-        features: Optional[List[str]] = None,
-        time_limit: Optional[float] = None,
+        data: TimeSeriesDataFrame | None = None,
+        model: str | None = None,
+        metric: str | TimeSeriesScorer | None = None,
+        features: list[str] | None = None,
+        time_limit: float | None = None,
         method: Literal["naive", "permutation"] = "permutation",
         subsample_size: int = 50,
-        num_iterations: Optional[int] = None,
-        random_seed: Optional[int] = None,
+        num_iterations: int | None = None,
+        random_seed: int | None = None,
         relative_scores: bool = False,
         include_confidence_band: bool = True,
         confidence_level: float = 0.99,
@@ -272,9 +274,9 @@ class TimeSeriesLearner(AbstractLearner):
 
     def leaderboard(
         self,
-        data: Optional[TimeSeriesDataFrame] = None,
+        data: TimeSeriesDataFrame | None = None,
         extra_info: bool = False,
-        extra_metrics: Optional[List[Union[str, TimeSeriesScorer]]] = None,
+        extra_metrics: list[str | TimeSeriesScorer] | None = None,
         use_cache: bool = True,
     ) -> pd.DataFrame:
         if data is not None:
@@ -283,7 +285,7 @@ class TimeSeriesLearner(AbstractLearner):
             data, extra_info=extra_info, extra_metrics=extra_metrics, use_cache=use_cache
         )
 
-    def get_info(self, include_model_info: bool = False, **kwargs) -> Dict[str, Any]:
+    def get_info(self, include_model_info: bool = False, **kwargs) -> dict[str, Any]:
         learner_info = super().get_info(include_model_info=include_model_info)
         trainer = self.load_trainer()
         trainer_info = trainer.get_info(include_model_info=include_model_info)
@@ -301,31 +303,63 @@ class TimeSeriesLearner(AbstractLearner):
         return learner_info
 
     def persist_trainer(
-        self, models: Union[Literal["all", "best"], List[str]] = "all", with_ancestors: bool = False
-    ) -> List[str]:
+        self, models: Literal["all", "best"] | list[str] = "all", with_ancestors: bool = False
+    ) -> list[str]:
         """Loads models and trainer in memory so that they don't have to be
         loaded during predictions
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models
             List of models persisted in memory
         """
         self.trainer = self.load_trainer()
         return self.trainer.persist(models, with_ancestors=with_ancestors)
 
-    def unpersist_trainer(self) -> List[str]:
+    def unpersist_trainer(self) -> list[str]:
         """Unloads models and trainer from memory. Models will have to be reloaded from disk
         when predicting.
 
         Returns
         -------
-        list_of_models : List[str]
+        list_of_models
             List of models removed from memory
         """
         unpersisted_models = self.load_trainer().unpersist()
         self.trainer = None  # type: ignore
         return unpersisted_models
 
-    def refit_full(self, model: str = "all") -> Dict[str, str]:
+    def refit_full(self, model: str = "all") -> dict[str, str]:
         return self.load_trainer().refit_full(model=model)
+
+    def backtest_predictions(
+        self,
+        data: TimeSeriesDataFrame | None,
+        model_names: list[str],
+        num_val_windows: int | None = None,
+        val_step_size: int | None = None,
+        use_cache: bool = True,
+    ) -> dict[str, list[TimeSeriesDataFrame]]:
+        if data is not None:
+            data = self.feature_generator.transform(data)
+        return self.load_trainer().backtest_predictions(
+            model_names=model_names,
+            data=data,
+            num_val_windows=num_val_windows,
+            val_step_size=val_step_size,
+            use_cache=use_cache,
+        )
+
+    def backtest_targets(
+        self,
+        data: TimeSeriesDataFrame | None,
+        num_val_windows: int | None = None,
+        val_step_size: int | None = None,
+    ) -> list[TimeSeriesDataFrame]:
+        if data is not None:
+            data = self.feature_generator.transform(data)
+        return self.load_trainer().backtest_targets(
+            data=data,
+            num_val_windows=num_val_windows,
+            val_step_size=val_step_size,
+        )

autogluon/timeseries/metrics/__init__.py

@@ -1,11 +1,17 @@
+from __future__ import annotations
+
 from pprint import pformat
-from typing import Type, Union
+from typing import Any, Sequence, Type
+
+import numpy as np
 
 from .abstract import TimeSeriesScorer
 from .point import MAE, MAPE, MASE, MSE, RMSE, RMSLE, RMSSE, SMAPE, WAPE, WCD
 from .quantile import SQL, WQL
 
 __all__ = [
+    "TimeSeriesScorer",
+    "check_get_evaluation_metric",
     "MAE",
     "MAPE",
     "MASE",
@@ -22,7 +28,7 @@ __all__ = [
 
 DEFAULT_METRIC_NAME = "WQL"
 
-AVAILABLE_METRICS = {
+AVAILABLE_METRICS: dict[str, Type[TimeSeriesScorer]] = {
     "MASE": MASE,
     "MAPE": MAPE,
     "SMAPE": SMAPE,
@@ -42,33 +48,61 @@ DEPRECATED_METRICS = {
 }
 
 # Experimental metrics that are not yet user facing
-EXPERIMENTAL_METRICS = {
+EXPERIMENTAL_METRICS: dict[str, Type[TimeSeriesScorer]] = {
     "WCD": WCD,
 }
 
 
 def check_get_evaluation_metric(
-    eval_metric: Union[str, TimeSeriesScorer, Type[TimeSeriesScorer], None] = None
+    eval_metric: str | TimeSeriesScorer | Type[TimeSeriesScorer] | None,
+    prediction_length: int,
+    seasonal_period: int | None = None,
+    horizon_weight: Sequence[float] | np.ndarray | None = None,
 ) -> TimeSeriesScorer:
+    """Factory method for TimeSeriesScorer objects.
+
+    Returns
+    -------
+    scorer
+        A `TimeSeriesScorer` object based on the provided `eval_metric`.
+
+        `scorer.prediction_length` is always set to the `prediction_length` provided to this method.
+
+        If `seasonal_period` is not `None`, then `scorer.seasonal_period` is set to this value. Otherwise the original
+        value of `seasonal_period` is kept.
+
+        If `horizon_weight` is not `None`, then `scorer.horizon_weight` is set to this value. Otherwise the original
+        value of `horizon_weight` is kept.
+    """
     scorer: TimeSeriesScorer
+    metric_kwargs: dict[str, Any] = dict(
+        prediction_length=prediction_length, seasonal_period=seasonal_period, horizon_weight=horizon_weight
+    )
     if isinstance(eval_metric, TimeSeriesScorer):
         scorer = eval_metric
+        scorer.prediction_length = prediction_length
+        if seasonal_period is not None:
+            scorer.seasonal_period = seasonal_period
+        if horizon_weight is not None:
+            scorer.horizon_weight = scorer.check_get_horizon_weight(
+                horizon_weight, prediction_length=prediction_length
+            )
     elif isinstance(eval_metric, type) and issubclass(eval_metric, TimeSeriesScorer):
         # e.g., user passed `eval_metric=CustomMetric` instead of `eval_metric=CustomMetric()`
-        scorer = eval_metric()
+        scorer = eval_metric(**metric_kwargs)
     elif isinstance(eval_metric, str):
         metric_name = DEPRECATED_METRICS.get(eval_metric, eval_metric).upper()
         if metric_name in AVAILABLE_METRICS:
-            scorer = AVAILABLE_METRICS[metric_name]()
+            scorer = AVAILABLE_METRICS[metric_name](**metric_kwargs)
         elif metric_name in EXPERIMENTAL_METRICS:
-            scorer = EXPERIMENTAL_METRICS[metric_name]()
+            scorer = EXPERIMENTAL_METRICS[metric_name](**metric_kwargs)
         else:
             raise ValueError(
                 f"Time series metric {eval_metric} not supported. Available metrics are:\n"
                 f"{pformat(sorted(AVAILABLE_METRICS.keys()))}"
             )
     elif eval_metric is None:
-        scorer = AVAILABLE_METRICS[DEFAULT_METRIC_NAME]()
+        scorer = AVAILABLE_METRICS[DEFAULT_METRIC_NAME](**metric_kwargs)
     else:
         raise ValueError(
             f"eval_metric must be of type str, TimeSeriesScorer or None "

autogluon/timeseries/metrics/abstract.py

@@ -1,4 +1,5 @@
-from typing import Optional, Tuple, Union
+import warnings
+from typing import Sequence, overload
 
 import numpy as np
 import pandas as pd
@@ -15,6 +16,18 @@ class TimeSeriesScorer:
 
     Follows the design of ``autogluon.core.metrics.Scorer``.
 
+    Parameters
+    ----------
+    prediction_length : int, default = 1
+        The length of the forecast horizon. The predictions provided to the ``TimeSeriesScorer`` are expected to contain
+        a forecast for this many time steps for each time series.
+    seasonal_period : int or None, default = None
+        Seasonal period used to compute some evaluation metrics such as mean absolute scaled error (MASE). Defaults to
+        ``None``, in which case the seasonal period is computed based on the data frequency.
+    horizon_weight : Sequence[float], np.ndarray or None, default = None
+        Weight assigned to each time step in the forecast horizon when computing the metric. If provided, the
+        ``horizon_weight`` will be stored as a numpy array of shape ``[1, prediction_length]``.
+
     Attributes
     ----------
     greater_is_better_internal : bool, default = False
@@ -30,15 +43,28 @@ class TimeSeriesScorer:
         Whether the given metric uses the quantile predictions. Some models will modify the training procedure if they
         are trained to optimize a quantile metric.
     equivalent_tabular_regression_metric : str
-        Name of an equivalent metric used by AutoGluon-Tabular with ``problem_type="regression"``. Used by models that
-        train a TabularPredictor under the hood. This attribute should only be specified by point forecast metrics.
+        Name of an equivalent metric used by AutoGluon-Tabular with ``problem_type="regression"``. Used by forecasting
+        models that train tabular regression models under the hood. This attribute should only be specified by point
+        forecast metrics.
     """
 
     greater_is_better_internal: bool = False
     optimum: float = 0.0
     optimized_by_median: bool = False
     needs_quantile: bool = False
-    equivalent_tabular_regression_metric: Optional[str] = None
+    equivalent_tabular_regression_metric: str | None = None
+
+    def __init__(
+        self,
+        prediction_length: int = 1,
+        seasonal_period: int | None = None,
+        horizon_weight: Sequence[float] | None = None,
+    ):
+        self.prediction_length = int(prediction_length)
+        if self.prediction_length < 1:
+            raise ValueError(f"prediction_length must be >= 1 (received {prediction_length})")
+        self.seasonal_period = seasonal_period
+        self.horizon_weight = self.check_get_horizon_weight(horizon_weight, prediction_length=prediction_length)
 
     @property
     def sign(self) -> int:
@@ -66,18 +92,25 @@ class TimeSeriesScorer:
         self,
         data: TimeSeriesDataFrame,
         predictions: TimeSeriesDataFrame,
-        prediction_length: int = 1,
         target: str = "target",
-        seasonal_period: Optional[int] = None,
         **kwargs,
     ) -> float:
-        seasonal_period = get_seasonality(data.freq) if seasonal_period is None else seasonal_period
+        seasonal_period = get_seasonality(data.freq) if self.seasonal_period is None else self.seasonal_period
 
-        data_past = data.slice_by_timestep(None, -prediction_length)
-        data_future = data.slice_by_timestep(-prediction_length, None)
+        if "prediction_length" in kwargs:
+            warnings.warn(
+                "Passing `prediction_length` to `TimeSeriesScorer.__call__` is deprecated and will be removed in v2.0. "
+                "Please set the `eval_metric.prediction_length` attribute instead.",
+                category=FutureWarning,
+            )
+            self.prediction_length = kwargs["prediction_length"]
+            self.horizon_weight = self.check_get_horizon_weight(self.horizon_weight, self.prediction_length)
+
+        data_past = data.slice_by_timestep(None, -self.prediction_length)
+        data_future = data.slice_by_timestep(-self.prediction_length, None)
 
         assert not predictions.isna().any().any(), "Predictions contain NaN values."
-        assert (predictions.num_timesteps_per_item() == prediction_length).all()
+        assert (predictions.num_timesteps_per_item() == self.prediction_length).all()
         assert data_future.index.equals(predictions.index), "Prediction and data indices do not match."
 
         try:
@@ -140,7 +173,7 @@ class TimeSeriesScorer:
     ) -> None:
         """Compute auxiliary metrics on past data (before forecast horizon), if the chosen metric requires it.
 
-        This method should only be implemented by metrics that rely on historic (in-sample) data, such as Mean Absolute
+        This method should only be implemented by metrics that rely on historical (in-sample) data, such as Mean Absolute
         Scaled Error (MASE) https://en.wikipedia.org/wiki/Mean_absolute_scaled_error.
 
         We keep this method separate from :meth:`compute_metric` to avoid redundant computations when fitting ensemble.
@@ -159,21 +192,21 @@ class TimeSeriesScorer:
         return self.optimum - self.score(*args, **kwargs)
 
     @staticmethod
-    def _safemean(array: Union[np.ndarray, pd.Series]) -> float:
+    def _safemean(array: np.ndarray | pd.Series) -> float:
         """Compute mean of a numpy array-like object, ignoring inf, -inf and nan values."""
         return float(np.mean(array[np.isfinite(array)]))
 
     @staticmethod
     def _get_point_forecast_score_inputs(
         data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target"
-    ) -> Tuple[pd.Series, pd.Series]:
+    ) -> tuple[pd.Series, pd.Series]:
         """Get inputs necessary to compute point forecast metrics.
 
         Returns
         -------
-        y_true : pd.Series, shape [num_items * prediction_length]
+        y_true
             Target time series values during the forecast horizon.
-        y_pred : pd.Series, shape [num_items * prediction_length]
+        y_pred
             Predicted time series values during the forecast horizon.
         """
         y_true = data_future[target]
@@ -183,16 +216,16 @@ class TimeSeriesScorer:
     @staticmethod
     def _get_quantile_forecast_score_inputs(
         data_future: TimeSeriesDataFrame, predictions: TimeSeriesDataFrame, target: str = "target"
-    ) -> Tuple[pd.Series, pd.DataFrame, np.ndarray]:
+    ) -> tuple[pd.Series, pd.DataFrame, np.ndarray]:
         """Get inputs necessary to compute quantile forecast metrics.
 
         Returns
         -------
-        y_true : pd.Series, shape [num_items * prediction_length]
+        y_true
             Target time series values during the forecast horizon.
-        q_pred : pd.DataFrame, shape [num_items * prediction_length, num_quantiles]
+        q_pred
             Quantile forecast for each predicted quantile level. Column order corresponds to ``quantile_levels``.
-        quantile_levels : np.ndarray, shape [num_quantiles]
+        quantile_levels
             Quantile levels for which the forecasts are generated (as floats).
         """
         quantile_columns = [col for col in predictions.columns if col != "mean"]
@@ -200,3 +233,40 @@ class TimeSeriesScorer:
         q_pred = pd.DataFrame(predictions[quantile_columns])
         quantile_levels = np.array(quantile_columns, dtype=float)
         return y_true, q_pred, quantile_levels
+
+    @overload
+    @staticmethod
+    def check_get_horizon_weight(horizon_weight: None, prediction_length: int) -> None: ...
+    @overload
+    @staticmethod
+    def check_get_horizon_weight(
+        horizon_weight: Sequence[float] | np.ndarray, prediction_length: int
+    ) -> np.ndarray: ...
+
+    @staticmethod
+    def check_get_horizon_weight(
+        horizon_weight: Sequence[float] | np.ndarray | None, prediction_length: int
+    ) -> np.ndarray | None:
+        """Convert horizon_weight to a non-negative numpy array that sums up to prediction_length.
+        Raises an exception if horizon_weight has an invalid shape or contains invalid values.
+
+        Returns
+        -------
+        horizon_weight
+            None if the input is None, otherwise a numpy array of shape [1, prediction_length].
+        """
+        if horizon_weight is None:
+            return None
+        horizon_weight_np = np.ravel(horizon_weight).astype(np.float64)
+        if horizon_weight_np.shape != (prediction_length,):
+            raise ValueError(
+                f"horizon_weight must have length equal to {prediction_length=} (got {len(horizon_weight)=})"
+            )
+        if not (horizon_weight_np >= 0).all():
+            raise ValueError(f"All values in horizon_weight must be >= 0 (got {horizon_weight})")
+        if not horizon_weight_np.sum() > 0:
+            raise ValueError(f"At least some values in horizon_weight must be > 0 (got {horizon_weight})")
+        if not np.isfinite(horizon_weight_np).all():
+            raise ValueError(f"All horizon_weight values must be finite (got {horizon_weight})")
+        horizon_weight_np = horizon_weight_np * prediction_length / horizon_weight_np.sum()
+        return horizon_weight_np.reshape([1, prediction_length])