Encoder Base Classes

class darts.dataprocessing.encoders.encoder_base.CovariatesIndexGenerator(input_chunk_length=None, output_chunk_length=None, lags_covariates=None)

Bases: ABC

CovariatesIndexGenerator generates a time index for covariates at training and inference / prediction time with methods generate_train_idx(), and generate_inference_idx(). Without user covariates, it generates the minimum required covariate times spans for the corresponding scenarios described below. With user covariates, it simply copies and returns the covariates time index.

It can be used: A in combination with LocalForecastingModel, or in a model agnostic scenario:

All parameters can be ignored. This scenario is only supported by FutureCovariatesIndexGenerator.

B in combination with RegressionModel:

Set input_chunk_length, output_chunk_length, and lags_covariates. input_chunk_length is the absolute value of the minimum target lag abs(min(lags)) used with the regression model. Set output_chunk_length, and lags_covariates with the identical values used at forecasting model creation. For the covariates lags, use lags_past_covariates for class:PastCovariatesIndexGenerator, and lags_future_covariates for class:PastCovariatesIndexGenerator.

C in combination with TorchForecastingModel:

Set input_chunk_length, and output_chunk_length with the identical values used at forecasting model creation.

Parameters

• input_chunk_length (Optional[int, None]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length for TorchForecastingModel, or to the absolute minimum target lag value abs(min(lags)) for RegressionModel.

• output_chunk_length (Optional[int, None]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for both TorchForecastingModel, and RegressionModel.

• lags_covariates (Optional[list[int], None]) – Optionally, a list of integers giving the covariates lags used for Darts’ RegressionModels. Only required in scenario B. Corresponds to the lag values from lags_past_covariates for past covariates, and lags_future_covariates for future covariates.

Attributes

base_component_name

Returns the index generator base component name.

Methods

generate_inference_idx(n, target[, covariates])	Generates/extracts time index (or integer index) for covariates at model inference / prediction time.
generate_train_idx(target[, covariates])	Generates/extracts time index (or integer index) for covariates at model training time.
generate_train_inference_idx(n, target[, ...])	Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

abstract property base_component_name: str

Returns the index generator base component name. - “pc”: past covariates - “fc”: future covariates

Return type

str

abstract generate_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model inference / prediction time.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

abstract generate_train_idx(target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model training time.

Parameters

• target (TimeSeries) – The target TimeSeries used during training.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time span for training a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

generate_train_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used for training and inference / prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training and inference / prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing training and inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

class darts.dataprocessing.encoders.encoder_base.Encoder

Bases: ABC

Abstract class for all encoders

Attributes

fit_called	Returns whether the Encoder object has been fitted.
requires_fit	Whether the Encoder sub class must be fit with Encoder.encode_train() before inference with Encoder.encode_inference().

Methods

encode_inference(n, target[, covariates, ...])	Each subclass must implement a method to encode the covariates index for prediction.
encode_train(target[, covariates, ...])	Each subclass must implement a method to encode the covariates index for training.
encode_train_inference(n, target[, ...])	Each subclass must implement a method to encode the covariates index for training and prediction.

abstract encode_inference(n, target, covariates=None, merge_covariates=True, **kwargs)

Each subclass must implement a method to encode the covariates index for prediction.

Parameters

• n (int) – The forecast horizon

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series

• covariates (Optional[TimeSeries, None]) – Optionally, the past or future covariates used for prediction.

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

abstract encode_train(target, covariates=None, merge_covariates=True, **kwargs)

Each subclass must implement a method to encode the covariates index for training.

Parameters

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the past or future covariates used for training.

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

abstract encode_train_inference(n, target, covariates=None, merge_covariates=True, **kwargs)

Each subclass must implement a method to encode the covariates index for training and prediction.

Parameters

• n (int) – The forecast horizon

• target (TimeSeries) – The target TimeSeries used during training and prediction.

• covariates (Optional[TimeSeries, None]) – Optionally, the past or future covariates used for training and prediction.

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

property fit_called: bool

Returns whether the Encoder object has been fitted.

Return type

bool

abstract property requires_fit: bool

Whether the Encoder sub class must be fit with Encoder.encode_train() before inference with Encoder.encode_inference().

Return type

bool

class darts.dataprocessing.encoders.encoder_base.FutureCovariatesIndexGenerator(input_chunk_length=None, output_chunk_length=None, lags_covariates=None)

Bases: CovariatesIndexGenerator

Generates index for future covariates on train and inference datasets.

Attributes

base_component_name

Returns the index generator base component name.

Methods

generate_inference_idx(n, target[, covariates])	Generates/extracts time index (or integer index) for covariates at model inference / prediction time.
generate_train_idx(target[, covariates])	Generates/extracts time index (or integer index) for covariates at model training time.
generate_train_inference_idx(n, target[, ...])	Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

CovariatesIndexGenerator generates a time index for covariates at training and inference / prediction time with methods generate_train_idx(), and generate_inference_idx(). Without user covariates, it generates the minimum required covariate times spans for the corresponding scenarios described below. With user covariates, it simply copies and returns the covariates time index.

It can be used: A in combination with LocalForecastingModel, or in a model agnostic scenario:

All parameters can be ignored. This scenario is only supported by FutureCovariatesIndexGenerator.

B in combination with RegressionModel:

Set input_chunk_length, output_chunk_length, and lags_covariates. input_chunk_length is the absolute value of the minimum target lag abs(min(lags)) used with the regression model. Set output_chunk_length, and lags_covariates with the identical values used at forecasting model creation. For the covariates lags, use lags_past_covariates for class:PastCovariatesIndexGenerator, and lags_future_covariates for class:PastCovariatesIndexGenerator.

C in combination with TorchForecastingModel:

Set input_chunk_length, and output_chunk_length with the identical values used at forecasting model creation.

Parameters

• input_chunk_length (Optional[int, None]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length for TorchForecastingModel, or to the absolute minimum target lag value abs(min(lags)) for RegressionModel.

• output_chunk_length (Optional[int, None]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for both TorchForecastingModel, and RegressionModel.

• lags_covariates (Optional[list[int], None]) – Optionally, a list of integers giving the covariates lags used for Darts’ RegressionModels. Only required in scenario B. Corresponds to the lag values from lags_past_covariates for past covariates, and lags_future_covariates for future covariates.

Attributes

base_component_name

Returns the index generator base component name.

Methods

generate_inference_idx(n, target[, covariates])	Generates/extracts time index (or integer index) for covariates at model inference / prediction time.
generate_train_idx(target[, covariates])	Generates/extracts time index (or integer index) for covariates at model training time.
generate_train_inference_idx(n, target[, ...])	Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

property base_component_name: str

Returns the index generator base component name. - “pc”: past covariates - “fc”: future covariates

Return type

str

generate_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model inference / prediction time.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

generate_train_idx(target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model training time.

Parameters

• target (TimeSeries) – The target TimeSeries used during training.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time span for training a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

generate_train_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used for training and inference / prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training and inference / prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing training and inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

class darts.dataprocessing.encoders.encoder_base.PastCovariatesIndexGenerator(input_chunk_length=None, output_chunk_length=None, lags_covariates=None)

Bases: CovariatesIndexGenerator

Generates index for past covariates on train and inference datasets

Attributes

base_component_name

Returns the index generator base component name.

Methods

generate_inference_idx(n, target[, covariates])	Generates/extracts time index (or integer index) for covariates at model inference / prediction time.
generate_train_idx(target[, covariates])	Generates/extracts time index (or integer index) for covariates at model training time.
generate_train_inference_idx(n, target[, ...])	Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

CovariatesIndexGenerator generates a time index for covariates at training and inference / prediction time with methods generate_train_idx(), and generate_inference_idx(). Without user covariates, it generates the minimum required covariate times spans for the corresponding scenarios described below. With user covariates, it simply copies and returns the covariates time index.

It can be used: A in combination with LocalForecastingModel, or in a model agnostic scenario:

All parameters can be ignored. This scenario is only supported by FutureCovariatesIndexGenerator.

B in combination with RegressionModel:

Set input_chunk_length, output_chunk_length, and lags_covariates. input_chunk_length is the absolute value of the minimum target lag abs(min(lags)) used with the regression model. Set output_chunk_length, and lags_covariates with the identical values used at forecasting model creation. For the covariates lags, use lags_past_covariates for class:PastCovariatesIndexGenerator, and lags_future_covariates for class:PastCovariatesIndexGenerator.

C in combination with TorchForecastingModel:

Set input_chunk_length, and output_chunk_length with the identical values used at forecasting model creation.

Parameters

• input_chunk_length (Optional[int, None]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length for TorchForecastingModel, or to the absolute minimum target lag value abs(min(lags)) for RegressionModel.

• output_chunk_length (Optional[int, None]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for both TorchForecastingModel, and RegressionModel.

• lags_covariates (Optional[list[int], None]) – Optionally, a list of integers giving the covariates lags used for Darts’ RegressionModels. Only required in scenario B. Corresponds to the lag values from lags_past_covariates for past covariates, and lags_future_covariates for future covariates.

Attributes

base_component_name

Returns the index generator base component name.

Methods

generate_inference_idx(n, target[, covariates])	Generates/extracts time index (or integer index) for covariates at model inference / prediction time.
generate_train_idx(target[, covariates])	Generates/extracts time index (or integer index) for covariates at model training time.
generate_train_inference_idx(n, target[, ...])	Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

property base_component_name: str

Returns the index generator base component name. - “pc”: past covariates - “fc”: future covariates

Return type

str

generate_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model inference / prediction time.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

generate_train_idx(target, covariates=None)

Generates/extracts time index (or integer index) for covariates at model training time.

Parameters

• target (TimeSeries) – The target TimeSeries used during training.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time span for training a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

generate_train_inference_idx(n, target, covariates=None)

Generates/extracts time index (or integer index) for covariates for training and inference / prediction.

Parameters

• n (int) – The forecasting horizon.

• target (TimeSeries) – The target TimeSeries used for training and inference / prediction as series.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training and inference / prediction. If given, the returned time index is equal to the covariates time index. Else, the returned time index covers the minimum required covariate time spans for performing training and inference / prediction with a specific forecasting model. These requirements are derived from parameters set at CovariatesIndexGenerator creation.

Return type

tuple[Union[DatetimeIndex, RangeIndex], Timestamp]

class darts.dataprocessing.encoders.encoder_base.SequentialEncoderTransformer(transformer, transform_mask)

Bases: object

SequentialEncoderTransformer applies transformation to the non-transformed encoded covariates output of SequentialEncoder.encode_train() and SequentialEncoder.encode_inference(). The transformer is fitted when transform() is called for the first time. This ensures proper transformation of train, validation and inference dataset covariates. User-supplied covariates are not transformed.

Attributes

fit_called

Return whether the transformer has been fitted.

Methods

transform(covariates)

This method applies transformation to the non-transformed encoded covariates output of SequentialEncoder._encode_sequence() after being merged with user-defined covariates.

Parameters

• transformer (FittableDataTransformer) – A FittableDataTransformer object with a fit_transform() and transform() method.

• transform_mask (list[bool]) – A boolean 1-D mask specifying which of the input covariates to transform() must be transformed.

Attributes

fit_called

Return whether the transformer has been fitted.

Methods

transform(covariates)

This method applies transformation to the non-transformed encoded covariates output of SequentialEncoder._encode_sequence() after being merged with user-defined covariates.

property fit_called: bool

Return whether the transformer has been fitted.

Return type

bool

transform(covariates)

This method applies transformation to the non-transformed encoded covariates output of SequentialEncoder._encode_sequence() after being merged with user-defined covariates. The transformer is fitted when transform() is called for the first time. This ensures proper transformation of train, validation and inference dataset covariates. The masks ensure that no covariates are transformed that user explicitly supplied to TorchForecastingModel.fit() and TorchForecastingModel.predict()

Parameters

covariates (list[TimeSeries]) – The non-transformed encoded covariates output of SequentialEncoder._encode_sequence() before merging with user-defined covariates.

Return type

list[TimeSeries]

class darts.dataprocessing.encoders.encoder_base.SingleEncoder(index_generator)

Bases: Encoder, ABC

SingleEncoder: Abstract class for single index encoders. Single encoders can be used to implement new encoding techniques. Each single encoder must implement an _encode() method that carries the encoding logic.

The _encode() method must take an index as input and generate a encoded single TimeSeries as output.

Attributes

accept_transformer	Whether the SingleEncoder sub class accepts to be transformed.
base_component_name	Returns the base encoder base component name.
components	Returns the encoded component names.
encoding_n_components	The number of components in the SingleEncoder output.
fit_called	Returns whether the Encoder object has been fitted.
requires_fit	Whether the Encoder sub class must be fit with Encoder.encode_train() before inference with Encoder.encode_inference().

Methods

encode_inference(n, target[, covariates, ...])	Returns encoded index for inference/prediction.
encode_train(target[, covariates, ...])	Returns encoded index for training.
encode_train_inference(n, target[, ...])	Returns encoded index for inference/prediction.

Single encoders take an index_generator to generate the required index for encoding past and future covariates. See darts.utils.data.covariate_index_generators.py for the CovariatesIndexGenerator subclasses. For past covariates encoders, use a PastCovariatesIndexGenerator. For future covariates encoders use a FutureCovariatesIndexGenerator.

Parameters

index_generator (CovariatesIndexGenerator) – An instance of CovariatesIndexGenerator with methods generate_train_idx() and generate_inference_idx(). Used to generate the index for encoders.

Attributes

accept_transformer	Whether the SingleEncoder sub class accepts to be transformed.
base_component_name	Returns the base encoder base component name.
components	Returns the encoded component names.
encoding_n_components	The number of components in the SingleEncoder output.
fit_called	Returns whether the Encoder object has been fitted.
requires_fit	Whether the Encoder sub class must be fit with Encoder.encode_train() before inference with Encoder.encode_inference().

Methods

encode_inference(n, target[, covariates, ...])	Returns encoded index for inference/prediction.
encode_train(target[, covariates, ...])	Returns encoded index for training.
encode_train_inference(n, target[, ...])	Returns encoded index for inference/prediction.

abstract property accept_transformer: list[bool]

Whether the SingleEncoder sub class accepts to be transformed.

Return type

list[bool]

abstract property base_component_name: str

Returns the base encoder base component name. The string follows the given format: “darts_enc_{covariates_temp}_{encoder}_{attribute}”, where the elements are:

• covariates_temp: “pc” or “fc” for past, or future covariates respectively.

• encoder: the SingleEncoder type used:

  • “cyc” (cyclic temporal encoder),

  • “dta” (datetime attribute encoder),

  • “pos” (positional integer index encoder),

  • “cus” (custom callable index encoder)

• attribute: the attribute used for the underlying encoder. Some examples:

  • “month_sin”, “month_cos” (for “cyc”)

  • “month” (for “dta”)

  • “relative” (for “pos”)

  • “custom” (for “cus”)

Return type

str

property components: Index

Returns the encoded component names. Only available after Encoder.encode_train() or Encoder.encode_inference() have been called.

Return type

Index

encode_inference(n, target, covariates=None, merge_covariates=True, **kwargs)

Returns encoded index for inference/prediction.

Parameters

• n (int) – The forecast horizon

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for prediction: past covariates if self.index_generator is a PastCovariatesIndexGenerator, future covariates if self.index_generator is a FutureCovariatesIndexGenerator

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

encode_train(target, covariates=None, merge_covariates=True, **kwargs)

Returns encoded index for training.

Parameters

• target (TimeSeries) – The target TimeSeries used during training or passed to prediction as series

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training: past covariates if self.index_generator is a PastCovariatesIndexGenerator, future covariates if self.index_generator is a FutureCovariatesIndexGenerator

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

encode_train_inference(n, target, covariates=None, merge_covariates=True, **kwargs)

Returns encoded index for inference/prediction.

Parameters

• n (int) – The forecast horizon

• target (TimeSeries) – The target TimeSeries used during training and prediction.

• covariates (Optional[TimeSeries, None]) – Optionally, the covariates used for training and prediction: past covariates if self.index_generator is a PastCovariatesIndexGenerator, future covariates if self.index_generator is a FutureCovariatesIndexGenerator

• merge_covariates (bool) – Whether to merge the encoded TimeSeries with covariates.

Return type

TimeSeries

abstract property encoding_n_components: int

The number of components in the SingleEncoder output.

Return type

int

property fit_called: bool

Returns whether the Encoder object has been fitted.

Return type

bool

abstract property requires_fit: bool

Whether the Encoder sub class must be fit with Encoder.encode_train() before inference with Encoder.encode_inference().

Return type

bool

previous

Time Axis Encoders

next

Time Axes Encoders