Skip to main content
The most important train signal is the forecast error, which is the difference between the observed value yτy_{\tau} and the prediction y^τ\hat{y}_{\tau}, at time yτy_{\tau}: eτ=yτy^ττ{t+1,,t+H}e_{\tau} = y_{\tau}-\hat{y}_{\tau} \qquad \qquad \tau \in \{t+1,\dots,t+H \} The train loss summarizes the forecast errors in different train optimization objectives. All the losses are torch.nn.modules which helps to automatically moved them across CPU/GPU/TPU devices with Pytorch Lightning.

BasePointLoss

Bases: Module Base class for point loss functions. Parameters:

1. Scale-dependent Errors

These metrics are on the same scale as the data.

Mean Absolute Error (MAE)

MAE

Bases: BasePointLoss Mean Absolute Error. Calculates Mean Absolute Error between y and y_hat. MAE measures the relative prediction accuracy of a forecasting method by calculating the deviation of the prediction and the true value at a given time and averages these devations over the length of the series. MAE(yτ,y^τ)=1Hτ=t+1t+Hyτy^τ\mathrm{MAE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} |y_{\tau} - \hat{y}_{\tau}| Parameters:

MAE.__call__

Calculate Mean Absolute Error between actual and predicted values. Parameters: Returns:

Mean Squared Error (MSE)

MSE

Bases: BasePointLoss Mean Squared Error. Calculates Mean Squared Error between y and y_hat. MSE measures the relative prediction accuracy of a forecasting method by calculating the squared deviation of the prediction and the true value at a given time, and averages these devations over the length of the series. MSE(yτ,y^τ)=1Hτ=t+1t+H(yτy^τ)2\mathrm{MSE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} (y_{\tau} - \hat{y}_{\tau})^{2} Parameters:

MSE.__call__

Calculate Mean Squared Error between actual and predicted values. Parameters: Returns:

Root Mean Squared Error (RMSE)

RMSE

Bases: BasePointLoss Root Mean Squared Error. Calculates Root Mean Squared Error between y and y_hat. RMSE measures the relative prediction accuracy of a forecasting method by calculating the squared deviation of the prediction and the observed value at a given time and averages these devations over the length of the series. Finally the RMSE will be in the same scale as the original time series so its comparison with other series is possible only if they share a common scale. RMSE has a direct connection to the L2 norm. RMSE(yτ,y^τ)=1Hτ=t+1t+H(yτy^τ)2\mathrm{RMSE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \sqrt{\frac{1}{H} \sum^{t+H}_{\tau=t+1} (y_{\tau} - \hat{y}_{\tau})^{2}} Parameters:

RMSE.__call__

Parameters: Returns:

2. Percentage errors

These metrics are unit-free, suitable for comparisons across series.

Mean Absolute Percentage Error (MAPE)

MAPE

Bases: BasePointLoss Mean Absolute Percentage Error Calculates Mean Absolute Percentage Error between y and y_hat. MAPE measures the relative prediction accuracy of a forecasting method by calculating the percentual deviation of the prediction and the observed value at a given time and averages these devations over the length of the series. The closer to zero an observed value is, the higher penalty MAPE loss assigns to the corresponding error. MAPE(yτ,y^τ)=1Hτ=t+1t+Hyτy^τyτ\mathrm{MAPE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \frac{|y_{\tau}-\hat{y}_{\tau}|}{|y_{\tau}|} Parameters:

MAPE.__call__

Parameters: Returns:

Symmetric MAPE (sMAPE)

SMAPE

Bases: BasePointLoss Symmetric Mean Absolute Percentage Error Calculates Symmetric Mean Absolute Percentage Error between y and y_hat. SMAPE measures the relative prediction accuracy of a forecasting method by calculating the relative deviation of the prediction and the observed value scaled by the sum of the absolute values for the prediction and observed value at a given time, then averages these devations over the length of the series. This allows the SMAPE to have bounds between 0% and 200% which is desireble compared to normal MAPE that may be undetermined when the target is zero. sMAPE2(yτ,y^τ)=1Hτ=t+1t+Hyτy^τyτ+y^τ\mathrm{sMAPE}_{2}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \frac{|y_{\tau}-\hat{y}_{\tau}|}{|y_{\tau}|+|\hat{y}_{\tau}|} Parameters:

SMAPE.__call__

Parameters: Returns:

3. Scale-independent Errors

These metrics measure the relative improvements versus baselines.

Mean Absolute Scaled Error (MASE)

MASE

Bases: BasePointLoss Mean Absolute Scaled Error Calculates the Mean Absolute Scaled Error between y and y_hat. MASE measures the relative prediction accuracy of a forecasting method by comparinng the mean absolute errors of the prediction and the observed value against the mean absolute errors of the seasonal naive model. The MASE partially composed the Overall Weighted Average (OWA), used in the M4 Competition. MASE(yτ,y^τ,y^τseason)=1Hτ=t+1t+Hyτy^τMAE(yτ,y^τseason)\mathrm{MASE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}, \mathbf{\hat{y}}^{season}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \frac{|y_{\tau}-\hat{y}_{\tau}|}{\mathrm{MAE}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{season}_{\tau})} Parameters:

MASE.__call__

Parameters: Returns:

Relative Mean Squared Error (relMSE)

relMSE

Bases: BasePointLoss Relative Mean Squared Error Computes Relative Mean Squared Error (relMSE), as proposed by Hyndman & Koehler (2006) as an alternative to percentage errors, to avoid measure unstability. relMSE(y,y^,y^benchmark)=MSE(y,y^)MSE(y,y^benchmark)\mathrm{relMSE}(\mathbf{y}, \mathbf{\hat{y}}, \mathbf{\hat{y}}^{benchmark}) = \frac{\mathrm{MSE}(\mathbf{y}, \mathbf{\hat{y}})}{\mathrm{MSE}(\mathbf{y}, \mathbf{\hat{y}}^{benchmark})} Parameters:

relMSE.__call__

Parameters: Returns:

4. Probabilistic Errors

These methods use statistical approaches for estimating unknown probability distributions using observed data. Maximum likelihood estimation involves finding the parameter values that maximize the likelihood function, which measures the probability of obtaining the observed data given the parameter values. MLE has good theoretical properties and efficiency under certain satisfied assumptions. On the non-parametric approach, quantile regression measures non-symmetrically deviation, producing under/over estimation.

Quantile Loss

QuantileLoss

Bases: BasePointLoss Quantile Loss. Computes the quantile loss between y and y_hat. QL measures the deviation of a quantile forecast. By weighting the absolute deviation in a non symmetric way, the loss pays more attention to under or over estimation. A common value for q is 0.5 for the deviation from the median (Pinball loss). QL(yτ,y^τ(q))=1Hτ=t+1t+H((1q)(y^τ(q)yτ)++q(yτy^τ(q))+)\mathrm{QL}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q)}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \Big( (1-q)\,( \hat{y}^{(q)}_{\tau} - y_{\tau} )_{+} + q\,( y_{\tau} - \hat{y}^{(q)}_{\tau} )_{+} \Big) Parameters:

QuantileLoss.__call__

Calculate quantile loss between actual and predicted values. Parameters: Returns:

Multi Quantile Loss (MQLoss)

MQLoss

Bases: BasePointLoss Multi-Quantile loss Calculates the Multi-Quantile loss (MQL) between y and y_hat. MQL calculates the average multi-quantile Loss for a given set of quantiles, based on the absolute difference between predicted quantiles and observed values. MQL(yτ,[y^τ(q1),...,y^τ(qn)])=1nqiQL(yτ,y^τ(qi))\mathrm{MQL}(\mathbf{y}_{\tau},[\mathbf{\hat{y}}^{(q_{1})}_{\tau}, ... ,\hat{y}^{(q_{n})}_{\tau}]) = \frac{1}{n} \sum_{q_{i}} \mathrm{QL}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q_{i})}_{\tau}) The limit behavior of MQL allows to measure the accuracy of a full predictive distribution mathbfhatF_tau\\mathbf{\\hat{F}}\_{\\tau} with the continuous ranked probability score (CRPS). This can be achieved through a numerical integration technique, that discretizes the quantiles and treats the CRPS integral with a left Riemann approximation, averaging over uniformly distanced quantiles. CRPS(yτ,F^τ)=01QL(yτ,y^τ(q))dq\mathrm{CRPS}(y_{\tau}, \mathbf{\hat{F}}_{\tau}) = \int^{1}_{0} \mathrm{QL}(y_{\tau}, \hat{y}^{(q)}_{\tau}) dq Parameters:

MQLoss.__call__

Computes the multi-quantile loss. Parameters: Returns:

Implicit Quantile Loss (IQLoss)

QuantileLayer

Bases: Module Implicit Quantile Layer from the paper IQN for Distributional Reinforcement Learning. Code from GluonTS: https://github.com/awslabs/gluonts/blob/61133ef6e2d88177b32ace4afc6843ab9a7bc8cd/src/gluonts/torch/distributions/implicit_quantile_network.py

IQLoss

Bases: QuantileLoss Implicit Quantile Loss. Computes the quantile loss between y and y_hat, with the quantile q provided as an input to the network. IQL measures the deviation of a quantile forecast. By weighting the absolute deviation in a non symmetric way, the loss pays more attention to under or over estimation. QL(yτ,y^τ(q))=1Hτ=t+1t+H((1q)(y^τ(q)yτ)++q(yτy^τ(q))+)\mathrm{QL}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q)}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \Big( (1-q)\,( \hat{y}^{(q)}_{\tau} - y_{\tau} )_{+} + q\,( y_{\tau} - \hat{y}^{(q)}_{\tau} )_{+} \Big) Parameters:

IQLoss.__call__

Calculate quantile loss between actual and predicted values. Parameters: Returns:

DistributionLoss

DistributionLoss

Bases: Module DistributionLoss This PyTorch module wraps the torch.distribution classes allowing it to interact with NeuralForecast models modularly. It shares the negative log-likelihood as the optimization objective and a sample method to generate empirically the quantiles defined by the level list. Additionally, it implements a distribution transformation that factorizes the scale-dependent likelihood parameters into a base scale and a multiplier efficiently learnable within the network’s non-linearities operating ranges. Available distributions:
  • Poisson
  • Normal
  • StudentT
  • NegativeBinomial
  • Tweedie
  • Bernoulli (Temporal Classifiers)
  • ISQF (Incremental Spline Quantile Function)
Parameters: Returns:

DistributionLoss.__call__

Computes the negative log-likelihood objective function. To estimate the following predictive distribution: P(yτθ)andlog(P(yτθ))\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta) \quad \mathrm{and} \quad -\log(\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta)) where theta\\theta represents the distributions parameters. It aditionally summarizes the objective signal using a weighted average using the mask tensor. Parameters: Returns:

Poisson Mixture Mesh (PMM)

PMM

Bases: Module Poisson Mixture Mesh This Poisson Mixture statistical model assumes independence across groups of data mathcalG=[g_i]\\mathcal{G}={[g\_{i}]}, and estimates relationships within the group. P(y[b][t+1:t+H])=[gi]GP(y[gi][τ])=β[gi](k=1Kwk(β,τ)[gi][t+1:t+H]Poisson(yβ,τ,λ^β,τ,k))\mathrm{P}\left(\mathbf{y}_{[b][t+1:t+H]}\right) = \prod_{ [g_{i}] \in \mathcal{G}} \mathrm{P} \left(\mathbf{y}_{[g_{i}][\tau]} \right) = \prod_{\beta\in[g_{i}]} \left(\sum_{k=1}^{K} w_k \prod_{(\beta,\tau) \in [g_i][t+1:t+H]} \mathrm{Poisson}(y_{\beta,\tau}, \hat{\lambda}_{\beta,\tau,k}) \right) Parameters:

PMM.__call__

Computes the negative log-likelihood objective function. To estimate the following predictive distribution: P(yτθ)andlog(P(yτθ))\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta) \quad \mathrm{and} \quad -\log(\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta)) where theta\\theta represents the distributions parameters. It aditionally summarizes the objective signal using a weighted average using the mask tensor. Parameters: Returns:

Gaussian Mixture Mesh (GMM)

GMM

Bases: Module Gaussian Mixture Mesh This Gaussian Mixture statistical model assumes independence across groups of data mathcalG=[g_i]\\mathcal{G}={[g\_{i}]}, and estimates relationships within the group. P(y[b][t+1:t+H])=[gi]GP(y[gi][τ])=β[gi](k=1Kwk(β,τ)[gi][t+1:t+H]Gaussian(yβ,τ,μ^β,τ,k,σβ,τ,k))\mathrm{P}\left(\mathbf{y}_{[b][t+1:t+H]}\right) = \prod_{ [g_{i}] \in \mathcal{G}} \mathrm{P}\left(\mathbf{y}_{[g_{i}][\tau]}\right)= \prod_{\beta\in[g_{i}]} \left(\sum_{k=1}^{K} w_k \prod_{(\beta,\tau) \in [g_i][t+1:t+H]} \mathrm{Gaussian}(y_{\beta,\tau}, \hat{\mu}_{\beta,\tau,k}, \sigma_{\beta,\tau,k})\right) Parameters:

GMM.__call__

Computes the negative log-likelihood objective function. To estimate the following predictive distribution: P(yτθ)andlog(P(yτθ))\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta) \quad \mathrm{and} \quad -\log(\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta)) where theta\\theta represents the distributions parameters. It aditionally summarizes the objective signal using a weighted average using the mask tensor. Parameters: Returns:

Negative Binomial Mixture Mesh (NBMM)

NBMM

Bases: Module Negative Binomial Mixture Mesh This N. Binomial Mixture statistical model assumes independence across groups of data mathcalG=[g_i]\\mathcal{G}={[g\_{i}]}, and estimates relationships within the group. P(y[b][t+1:t+H])=[gi]GP(y[gi][τ])=β[gi](k=1Kwk(β,τ)[gi][t+1:t+H]NBinomial(yβ,τ,r^β,τ,k,p^β,τ,k))\mathrm{P}\left(\mathbf{y}_{[b][t+1:t+H]}\right) = \prod_{ [g_{i}] \in \mathcal{G}} \mathrm{P}\left(\mathbf{y}_{[g_{i}][\tau]}\right)= \prod_{\beta\in[g_{i}]} \left(\sum_{k=1}^{K} w_k \prod_{(\beta,\tau) \in [g_i][t+1:t+H]} \mathrm{NBinomial}(y_{\beta,\tau}, \hat{r}_{\beta,\tau,k}, \hat{p}_{\beta,\tau,k})\right) Parameters:

NBMM.__call__

Computes the negative log-likelihood objective function. To estimate the following predictive distribution: P(yτθ)andlog(P(yτθ))\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta) \quad \mathrm{and} \quad -\log(\mathrm{P}(\mathbf{y}_{\tau}\,|\,\theta)) where theta\\theta represents the distributions parameters. It aditionally summarizes the objective signal using a weighted average using the mask tensor. Parameters: Returns:

5. Robustified Errors

Huber Loss

HuberLoss

Bases: BasePointLoss Huber Loss The Huber loss, employed in robust regression, is a loss function that exhibits reduced sensitivity to outliers in data when compared to the squared error loss. This function is also refered as SmoothL1. The Huber loss function is quadratic for small errors and linear for large errors, with equal values and slopes of the different sections at the two points where (y_tauhatytau)2(y\_{\\tau}-\\hat{y}_{\\tau})^{2}=ytauhaty_tau|y_{\\tau}-\\hat{y}\_{\\tau}|. Lδ(yτ,  y^τ)={12(yτy^τ)2  for yτy^τδδ (yτy^τ12δ),  otherwise.L_{\delta}(y_{\tau},\; \hat{y}_{\tau}) =\begin{cases}{\frac{1}{2}}(y_{\tau}-\hat{y}_{\tau})^{2}\;{\text{for }}|y_{\tau}-\hat{y}_{\tau}|\leq \delta \\ \delta \ \cdot \left(|y_{\tau}-\hat{y}_{\tau}|-{\frac {1}{2}}\delta \right),\;{\text{otherwise.}}\end{cases} where delta\\delta is a threshold parameter that determines the point at which the loss transitions from quadratic to linear, and can be tuned to control the trade-off between robustness and accuracy in the predictions. Parameters:

HuberLoss.__call__

Parameters: Returns:

Tukey Loss

TukeyLoss

Bases: BasePointLoss Tukey Loss The Tukey loss function, also known as Tukey’s biweight function, is a robust statistical loss function used in robust statistics. Tukey’s loss exhibits quadratic behavior near the origin, like the Huber loss; however, it is even more robust to outliers as the loss for large residuals remains constant instead of scaling linearly. The parameter cc in Tukey’s loss determines the ”saturation” point of the function: Higher values of cc enhance sensitivity, while lower values increase resistance to outliers. Lc(yτ,  y^τ)={c26[1(yτy^τc)2]3  for yτy^τcc26otherwise.L_{c}(y_{\tau},\; \hat{y}_{\tau}) =\begin{cases}{ \frac{c^{2}}{6}} \left[1-(\frac{y_{\tau}-\hat{y}_{\tau}}{c})^{2} \right]^{3} \;\text{for } |y_{\tau}-\hat{y}_{\tau}|\leq c \\ \frac{c^{2}}{6} \qquad \text{otherwise.} \end{cases} Please note that the Tukey loss function assumes the data to be stationary or normalized beforehand. If the error values are excessively large, the algorithm may need help to converge during optimization. It is advisable to employ small learning rates. Parameters:

TukeyLoss.__call__

Parameters: Returns:

Huberized Quantile Loss

HuberQLoss

Bases: BasePointLoss Huberized Quantile Loss The Huberized quantile loss is a modified version of the quantile loss function that combines the advantages of the quantile loss and the Huber loss. It is commonly used in regression tasks, especially when dealing with data that contains outliers or heavy tails. The Huberized quantile loss between y and y_hat measure the Huber Loss in a non-symmetric way. The loss pays more attention to under/over-estimation depending on the quantile parameter qq; and controls the trade-off between robustness and accuracy in the predictions with the parameter deltadelta. HuberQL(yτ,y^τ(q))=(1q)Lδ(yτ,  y^τ(q))1{y^τ(q)yτ}+qLδ(yτ,  y^τ(q))1{y^τ(q)<yτ}\mathrm{HuberQL}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q)}_{\tau}) = (1-q)\, L_{\delta}(y_{\tau},\; \hat{y}^{(q)}_{\tau}) \mathbb{1}\{ \hat{y}^{(q)}_{\tau} \geq y_{\tau} \} + q\, L_{\delta}(y_{\tau},\; \hat{y}^{(q)}_{\tau}) \mathbb{1}\{ \hat{y}^{(q)}_{\tau} < y_{\tau} \} Parameters:

HuberQLoss.__call__

Parameters: Returns:

Huberized MQLoss

HuberMQLoss

Bases: BasePointLoss Huberized Multi-Quantile loss The Huberized Multi-Quantile loss (HuberMQL) is a modified version of the multi-quantile loss function that combines the advantages of the quantile loss and the Huber loss. HuberMQL is commonly used in regression tasks, especially when dealing with data that contains outliers or heavy tails. The loss function pays more attention to under/over-estimation depending on the quantile list [q_1,q_2,dots][q\_{1},q\_{2},\\dots] parameter. It controls the trade-off between robustness and prediction accuracy with the parameter delta\\delta. HuberMQLδ(yτ,[y^τ(q1),...,y^τ(qn)])=1nqiHuberQLδ(yτ,y^τ(qi))\mathrm{HuberMQL}_{\delta}(\mathbf{y}_{\tau},[\mathbf{\hat{y}}^{(q_{1})}_{\tau}, ... ,\hat{y}^{(q_{n})}_{\tau}]) = \frac{1}{n} \sum_{q_{i}} \mathrm{HuberQL}_{\delta}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q_{i})}_{\tau}) Parameters:

HuberMQLoss.__call__

Parameters: Returns:

Huberized IQLoss

HuberIQLoss

Bases: HuberQLoss Implicit Huber Quantile Loss Computes the huberized quantile loss between y and y_hat, with the quantile q provided as an input to the network. HuberIQLoss measures the deviation of a huberized quantile forecast. By weighting the absolute deviation in a non symmetric way, the loss pays more attention to under or over estimation. HuberIQL(yτ,y^τ(q))=(1q)Lδ(yτ,  y^τ(q))1{y^τ(q)yτ}+qLδ(yτ,  y^τ(q))1{y^τ(q)<yτ}\mathrm{HuberIQL}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}^{(q)}_{\tau}) = (1-q)\, L_{\delta}(y_{\tau},\; \hat{y}^{(q)}_{\tau}) \mathbb{1}\{ \hat{y}^{(q)}_{\tau} \geq y_{\tau} \} + q\, L_{\delta}(y_{\tau},\; \hat{y}^{(q)}_{\tau}) \mathbb{1}\{ \hat{y}^{(q)}_{\tau} < y_{\tau} \} Parameters:

HuberIQLoss.__call__

Parameters: Returns:

6. Others

Accuracy

Accuracy

Bases: BasePointLoss Accuracy Computes the accuracy between categorical y and y_hat. This evaluation metric is only meant for evalution, as it is not differentiable. Accuracy(yτ,y^τ)=1Hτ=t+1t+H1{yτ==y^τ}\mathrm{Accuracy}(\mathbf{y}_{\tau}, \mathbf{\hat{y}}_{\tau}) = \frac{1}{H} \sum^{t+H}_{\tau=t+1} \mathrm{1}\{\mathbf{y}_{\tau}==\mathbf{\hat{y}}_{\tau}\}

Accuracy.__call__

Parameters: Returns:

Scaled Continuous Ranked Probability Score (sCRPS)

sCRPS

Bases: BasePointLoss Scaled Continues Ranked Probability Score Calculates a scaled variation of the CRPS, as proposed by Rangapuram (2021), to measure the accuracy of predicted quantiles y_hat compared to the observation y. This metric averages percentual weighted absolute deviations as defined by the quantile losses. sCRPS(y^τ(q),yτ)=2Ni01QL(y^τ(qyi,τ)qiyi,τdq\mathrm{sCRPS}(\mathbf{\hat{y}}^{(q)}_{\tau}, \mathbf{y}_{\tau}) = \frac{2}{N} \sum_{i} \int^{1}_{0} \frac{\mathrm{QL}(\mathbf{\hat{y}}^{(q}_{\tau} y_{i,\tau})_{q}}{\sum_{i} | y_{i,\tau} |} dq where mathbfhatytau(q\\mathbf{\\hat{y}}^{(q}_{\\tau} is the estimated quantile, and yi,tauy_{i,\\tau} are the target variable realizations. Parameters:

sCRPS.__call__

Parameters: Returns: