gluonts.model.npts package#

class gluonts.model.npts.KernelType(value)[source]#

Bases: str, enum.Enum

An enumeration.

exponential = 'exponential'#
uniform = 'uniform'#
class gluonts.model.npts.NPTSPredictor(prediction_length: int, context_length: Optional[int] = None, kernel_type: gluonts.model.npts._predictor.KernelType = KernelType.exponential, exp_kernel_weights: Union[float, List[float]] = 1.0, use_seasonal_model: bool = True, use_default_time_features: bool = True, num_default_time_features: int = 1, feature_scale: float = 1000.0)[source]#

Bases: gluonts.model.predictor.RepresentablePredictor

Implementation of Non-Parametric Time Series Forecaster.

Forecasts of NPTS for time step \(T\) are one of the previous values of the time series (these could be known values or predictions), sampled according to the (un-normalized) distribution \(q_T(t) > 0\) where \(0 <= t < T\).

The distribution \(q_T\) is expressed in terms of a feature map \(f(t)\) which associates a time step \(t\) with a \(D\)-dimensional feature map \([f_1(t), ..., f_D(t)]\). More details on the feature map can be found below.

We offer two types of distribution kernels.

Exponential Kernel (NPTS Forecaster)

The sampling distribution \(q_T\) for the exponential kernel can be weighted or unweighted and is defined as follows.

\[\begin{split}q_T(t) = \begin{cases} \exp( - \sum_{i=1}^D \alpha \left| f_i(t) - f_i(T) \right| ) & \text{unweighted}\\ \exp( - \sum_{i=1}^D \alpha_i \left| f_i(t) - f_i(T) \right| ) & \text{weighted} \end{cases}\end{split}\]

In the above definition \(\alpha > 0\) and \(\alpha_i > 0\) are user-defined sampling weights.

Uniform Kernel (Climatological Forecaster)

The sampling distribution \(q_T\) for the uniform kernel can be seasonal or not. The seasonal version is defined as follows.

\[\begin{split}q_T(t) = \begin{cases} 1.0 & \text{if }f(t) = f(T) \\ 0.0 & \text{otherwise} \end{cases}\end{split}\]

The not seasonal version is defined as the constant map.

\[q_T(t) = 1.0\]

Feature Map

The feature map \(f\) is configurable. The special case \(f(t) = [t]\) results in the so-called naive NPTS. For non-seasonal models, by default we have \(f(t) = [t]\) for the NPTS Forecaster (i.e., with the exponential kernel) and no features for the Climatological Forecaster (i.e., the uniform kernel).

For seasonal NPTS and seasonal Climatological, time features are determined based on the frequency of the time series are added to the default feature map.

The default time features for various frequencies are

\[\begin{split}f(t) = \begin{cases} [\mathit{MINUTE\_OF\_HOUR}(t)] & \text{for minutely frequency}\\ [\mathit{HOUR\_OF\_DAY}(t)] & \text{for hourly frequency}\\ [\mathit{DAY\_OF\_WEEK}(t)] & \text{for daily frequency}\\ [\mathit{DAY\_OF\_MONTH}(t)] & \text{for weekly frequency}\\ [\mathit{MONTH\_OF\_YEAR}(t)] & \text{for monthly frequency} \end{cases}\end{split}\]

During prediction, one can provide custom features in feat_dynamic_real (these have to be defined in both the training and the prediction range). If the model is seasonal, these custom features are added to the default feature map, otherwise they are ignored. If feat_dynamic_real is not empty, one can disable default time features by setting the flag use_default_time_features to False.

Parameters

  • prediction_length – number of time steps to predict

  • context_length – number of time-steps that are considered before making predictions (the default value of None corresponds to the case where all time steps in the history are considered)

  • kernel_type – the type of kernel to use (either “exponential” or “uniform”)

  • exp_kernel_weights – single weight \(\alpha\) or the weights for the features to use in the exponential kernel; currently, we use the single weight version and for seasonal NPTS we just rescale \(\alpha\) by feature_scale for seasonal features.

  • use_seasonal_model – whether to use seasonal variant

  • use_default_time_features – time features derived based on the frequency of the time series

  • num_default_time_features – this is not exposed; this parameter is for having more control on the number of default time features, as the date_feature_set adds too many per default.

  • feature_scale – scale for time (seasonal) features in order to sample past seasons with higher probability

predict(dataset: gluonts.dataset.Dataset, num_samples: int = 100, **kwargs) → Iterator[gluonts.model.forecast.SampleForecast][source]#

Compute forecasts for the time series in the provided dataset. This method is not implemented in this abstract class; please use one of the subclasses. :param dataset: The dataset containing the time series to predict.

Returns

Iterator over the forecasts, in the same order as the dataset iterable was provided.

Return type

Iterator[Forecast]

predict_time_series(ts: pandas.core.series.Series, num_samples: int, custom_features: Optional[numpy.ndarray] = None, item_id: Optional[Any] = None) → gluonts.model.forecast.SampleForecast[source]#

Given a training time series, this method generates Forecast object containing prediction samples for prediction_length time points.

The predictions are generated via weighted sampling where the weights are determined by the NPTSPredictor kernel type and feature map.

Parameters

  • ts – training time series object

  • custom_features – custom features (covariates) to use

  • num_samples – number of samples to draw

  • item_id – item_id to identify the time series

Returns

A prediction for the supplied ts and custom_features.

Return type

Forecast