gluonts.torch.model.deepar package#

class gluonts.torch.model.deepar.DeepAREstimator(freq: str, prediction_length: int, context_length: Optional[int] = None, num_layers: int = 2, hidden_size: int = 40, lr: float = 0.001, weight_decay: float = 1e-08, dropout_rate: float = 0.1, patience: int = 10, num_feat_dynamic_real: int = 0, num_feat_static_cat: int = 0, num_feat_static_real: int = 0, cardinality: Optional[List[int]] = None, embedding_dimension: Optional[List[int]] = None, distr_output: DistributionOutput = gluonts.torch.distributions.studentT.StudentTOutput(beta=0.0), scaling: bool = True, default_scale: Optional[float] = None, lags_seq: Optional[List[int]] = None, time_features: Optional[List[Callable[[PeriodIndex], ndarray]]] = None, num_parallel_samples: int = 100, batch_size: int = 32, num_batches_per_epoch: int = 50, imputation_method: Optional[MissingValueImputation] = None, trainer_kwargs: Optional[Dict[str, Any]] = None, train_sampler: Optional[InstanceSampler] = None, validation_sampler: Optional[InstanceSampler] = None, nonnegative_pred_samples: bool = False)[source]#

Bases: PyTorchLightningEstimator

Estimator class to train a DeepAR model, as described in [SFG17].

This class is uses the model defined in DeepARModel, and wraps it into a DeepARLightningModule for training purposes: training is performed using PyTorch Lightning’s pl.Trainer class.

Note: the code of this model is unrelated to the implementation behind SageMaker’s DeepAR Forecasting Algorithm.

Parameters:
  • freq – Frequency of the data to train on and predict.

  • prediction_length (int) – Length of the prediction horizon.

  • context_length – Number of steps to unroll the RNN for before computing predictions (default: None, in which case context_length = prediction_length).

  • num_layers – Number of RNN layers (default: 2).

  • hidden_size – Number of RNN cells for each layer (default: 40).

  • lr – Learning rate (default: 1e-3).

  • weight_decay – Weight decay regularization parameter (default: 1e-8).

  • dropout_rate – Dropout regularization parameter (default: 0.1).

  • patience – Patience parameter for learning rate scheduler.

  • num_feat_dynamic_real – Number of dynamic real features in the data (default: 0).

  • num_feat_static_real – Number of static real features in the data (default: 0).

  • num_feat_static_cat – Number of static categorical features in the data (default: 0).

  • cardinality – Number of values of each categorical feature. This must be set if num_feat_static_cat > 0 (default: None).

  • embedding_dimension – Dimension of the embeddings for categorical features (default: [min(50, (cat+1)//2) for cat in cardinality]).

  • distr_output – Distribution to use to evaluate observations and sample predictions (default: StudentTOutput()).

  • scaling – Whether to automatically scale the target values (default: true).

  • default_scale – Default scale that is applied if the context length window is completely unobserved. If not set, the scale in this case will be the mean scale in the batch.

  • lags_seq – Indices of the lagged target values to use as inputs of the RNN (default: None, in which case these are automatically determined based on freq).

  • time_features – List of time features, from gluonts.time_feature, to use as inputs of the RNN in addition to the provided data (default: None, in which case these are automatically determined based on freq).

  • num_parallel_samples – Number of samples per time series to that the resulting predictor should produce (default: 100).

  • batch_size – The size of the batches to be used for training (default: 32).

  • num_batches_per_epoch – Number of batches to be processed in each training epoch (default: 50).

  • trainer_kwargs – Additional arguments to provide to pl.Trainer for construction.

  • train_sampler – Controls the sampling of windows during training.

  • validation_sampler – Controls the sampling of windows during validation.

  • nonnegative_pred_samples – Should final prediction samples be non-negative? If yes, an activation function is applied to ensure non-negative. Observe that this is applied only to the final samples and this is not applied during training.

create_lightning_module() DeepARLightningModule[source]#

Create and return the network used for training (i.e., computing the loss).

Returns:

The network that computes the loss given input data.

Return type:

pl.LightningModule

create_predictor(transformation: Transformation, module: DeepARLightningModule) PyTorchPredictor[source]#

Create and return a predictor object.

Parameters:
  • transformation – Transformation to be applied to data before it goes into the model.

  • module – A trained pl.LightningModule object.

Returns:

A predictor wrapping a nn.Module used for inference.

Return type:

Predictor

create_training_data_loader(data: Dataset, module: DeepARLightningModule, shuffle_buffer_length: Optional[int] = None, **kwargs) Iterable[source]#

Create a data loader for training purposes.

Parameters:
  • data – Dataset from which to create the data loader.

  • module – The pl.LightningModule object that will receive the batches from the data loader.

Returns:

The data loader, i.e. and iterable over batches of data.

Return type:

Iterable

create_transformation() Transformation[source]#

Create and return the transformation needed for training and inference.

Returns:

The transformation that will be applied entry-wise to datasets, at training and inference time.

Return type:

Transformation

create_validation_data_loader(data: Dataset, module: DeepARLightningModule, **kwargs) Iterable[source]#

Create a data loader for validation purposes.

Parameters:
  • data – Dataset from which to create the data loader.

  • module – The pl.LightningModule object that will receive the batches from the data loader.

Returns:

The data loader, i.e. and iterable over batches of data.

Return type:

Iterable

classmethod derive_auto_fields(train_iter)[source]#
class gluonts.torch.model.deepar.DeepARLightningModule(model_kwargs: dict, lr: float = 0.001, weight_decay: float = 1e-08, patience: int = 10)[source]#

Bases: LightningModule

A pl.LightningModule class that can be used to train a DeepARModel with PyTorch Lightning.

This is a thin layer around a (wrapped) DeepARModel object, that exposes the methods to evaluate training and validation loss.

Parameters:
  • model_kwargs – Keyword arguments to construct the DeepARModel to be trained.

  • loss – Loss function to be used for training.

  • lr – Learning rate.

  • weight_decay – Weight decay regularization parameter.

  • patience – Patience parameter for learning rate scheduler.

configure_optimizers()[source]#

Returns the optimizer to use.

forward(*args, **kwargs)[source]#

Same as torch.nn.Module.forward().

Parameters:
  • *args – Whatever you decide to pass into the forward method.

  • **kwargs – Keyword arguments are also possible.

Returns:

Your model’s output

training_step(batch, batch_idx: int)[source]#

Execute training step.

validation_step(batch, batch_idx: int)[source]#

Execute validation step.

class gluonts.torch.model.deepar.DeepARModel(freq: str, context_length: int, prediction_length: int, num_feat_dynamic_real: int = 1, num_feat_static_real: int = 1, num_feat_static_cat: int = 1, cardinality: List[int] = [1], embedding_dimension: Optional[List[int]] = None, num_layers: int = 2, hidden_size: int = 40, dropout_rate: float = 0.1, distr_output: DistributionOutput = gluonts.torch.distributions.studentT.StudentTOutput(beta=0.0), lags_seq: Optional[List[int]] = None, scaling: bool = True, default_scale: Optional[float] = None, num_parallel_samples: int = 100, nonnegative_pred_samples: bool = False)[source]#

Bases: Module

Module implementing the DeepAR model, see [SFG17].

Note: the code of this model is unrelated to the implementation behind SageMaker’s DeepAR Forecasting Algorithm.

Parameters:
  • freq – String indicating the sampling frequency of the data to be processed.

  • context_length – Length of the RNN unrolling prior to the forecast date.

  • prediction_length – Number of time points to predict.

  • num_feat_dynamic_real – Number of dynamic real features that will be provided to forward.

  • num_feat_static_real – Number of static real features that will be provided to forward.

  • num_feat_static_cat – Number of static categorical features that will be provided to forward.

  • cardinality – List of cardinalities, one for each static categorical feature.

  • embedding_dimension – Dimension of the embedding space, one for each static categorical feature.

  • num_layers – Number of layers in the RNN.

  • hidden_size – Size of the hidden layers in the RNN.

  • dropout_rate – Dropout rate to be applied at training time.

  • distr_output – Type of distribution to be output by the model at each time step

  • lags_seq – Indices of the lagged observations that the RNN takes as input. For example, [1] indicates that the RNN only takes the observation at time t-1 to produce the output for time t; instead, [1, 25] indicates that the RNN takes observations at times t-1 and t-25 as input.

  • scaling – Whether to apply mean scaling to the observations (target).

  • default_scale – Default scale that is applied if the context length window is completely unobserved. If not set, the scale in this case will be the mean scale in the batch.

  • num_parallel_samples – Number of samples to produce when unrolling the RNN in the prediction time range.

  • nonnegative_pred_samples – Should final prediction samples be non-negative? If yes, an activation function is applied to ensure non-negative. Observe that this is applied only to the final samples and this is not applied during training.

describe_inputs(batch_size=1) InputSpec[source]#
forward(feat_static_cat: Tensor, feat_static_real: Tensor, past_time_feat: Tensor, past_target: Tensor, past_observed_values: Tensor, future_time_feat: Tensor, num_parallel_samples: Optional[int] = None) Tensor[source]#

Invokes the model on input data, and produce outputs future samples.

Parameters:
  • feat_static_cat – Tensor of static categorical features, shape: (batch_size, num_feat_static_cat).

  • feat_static_real – Tensor of static real features, shape: (batch_size, num_feat_static_real).

  • past_time_feat – Tensor of dynamic real features in the past, shape: (batch_size, past_length, num_feat_dynamic_real).

  • past_target – Tensor of past target values, shape: (batch_size, past_length).

  • past_observed_values – Tensor of observed values indicators, shape: (batch_size, past_length).

  • future_time_feat – (Optional) tensor of dynamic real features in the past, shape: (batch_size, prediction_length, num_feat_dynamic_real).

  • num_parallel_samples – How many future samples to produce. By default, self.num_parallel_samples is used.

log_prob(feat_static_cat: Tensor, feat_static_real: Tensor, past_time_feat: Tensor, past_target: Tensor, past_observed_values: Tensor, future_time_feat: Tensor, future_target: Tensor) Tensor[source]#
loss(feat_static_cat: ~torch.Tensor, feat_static_real: ~torch.Tensor, past_time_feat: ~torch.Tensor, past_target: ~torch.Tensor, past_observed_values: ~torch.Tensor, future_time_feat: ~torch.Tensor, future_target: ~torch.Tensor, future_observed_values: ~torch.Tensor, future_only: bool = False, aggregate_by=<built-in method mean of type object>) Tensor[source]#
output_distribution(params, scale=None, trailing_n=None) Distribution[source]#

Instantiate the output distribution.

Parameters:
  • params – Tuple of distribution parameters.

  • scale – (Optional) scale tensor.

  • trailing_n – If set, the output distribution is created only for the last trailing_n time points.

Returns:

Output distribution from the model.

Return type:

torch.distributions.Distribution

post_process_samples(samples: Tensor) Tensor[source]#

Method to enforce domain-specific constraints on the generated samples. For example, we can enforce forecasts to be nonnegative. :param samples: Tensor of samples

Return type:

Tensor of processed samples with the same shape.

prepare_rnn_input(feat_static_cat: Tensor, feat_static_real: Tensor, past_time_feat: Tensor, past_target: Tensor, past_observed_values: Tensor, future_time_feat: Tensor, future_target: Optional[Tensor] = None) Tuple[Tensor, Tensor, Tensor][source]#
unroll_lagged_rnn(feat_static_cat: Tensor, feat_static_real: Tensor, past_time_feat: Tensor, past_target: Tensor, past_observed_values: Tensor, future_time_feat: Tensor, future_target: Optional[Tensor] = None) Tuple[Tuple[Tensor, ...], Tensor, Tensor, Tensor, Tuple[Tensor, Tensor]][source]#

Applies the underlying RNN to the provided target data and covariates.

Parameters:
  • feat_static_cat – Tensor of static categorical features, shape: (batch_size, num_feat_static_cat).

  • feat_static_real – Tensor of static real features, shape: (batch_size, num_feat_static_real).

  • past_time_feat – Tensor of dynamic real features in the past, shape: (batch_size, past_length, num_feat_dynamic_real).

  • past_target – Tensor of past target values, shape: (batch_size, past_length).

  • past_observed_values – Tensor of observed values indicators, shape: (batch_size, past_length).

  • future_time_feat – Tensor of dynamic real features in the future, shape: (batch_size, prediction_length, num_feat_dynamic_real).

  • future_target – (Optional) tensor of future target values, shape: (batch_size, prediction_length).

Returns:

A tuple containing, in this order: - Parameters of the output distribution - Scaling factor applied to the target - Raw output of the RNN - Static input to the RNN - Output state from the RNN

Return type:

Tuple

Submodules#