Encoder Base Classes¶
- class darts.dataprocessing.encoders.encoder_base.CovariatesIndexGenerator(input_chunk_length=None, output_chunk_length=None, lags_covariates=None)[source]¶
Bases:
ABC
CovariatesIndexGenerator
generates a time index for covariates at training and inference / prediction time with methodsgenerate_train_idx()
, andgenerate_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
]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length forTorchForecastingModel
, or to the absolute minimum target lag value abs(min(lags)) forRegressionModel
.output_chunk_length (
Optional
[int
]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for bothTorchForecastingModel
, andRegressionModel
.lags_covariates (
Optional
[List
[int
]]) – 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
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)[source]¶
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- abstract generate_train_idx(target, covariates=None)[source]¶
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- generate_train_inference_idx(n, target, covariates=None)[source]¶
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- B in combination with
- class darts.dataprocessing.encoders.encoder_base.Encoder[source]¶
Bases:
ABC
Abstract class for all encoders
Attributes
Returns whether the Encoder object has been fitted.
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)[source]¶
Each subclass must implement a method to encode the covariates index for prediction.
- Parameters
n (
int
) – The forecast horizontarget (
TimeSeries
) – The target TimeSeries used during training or passed to prediction as seriescovariates (
Optional
[TimeSeries
]) – Optionally, the past or future covariates used for prediction.merge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- abstract encode_train(target, covariates=None, merge_covariates=True, **kwargs)[source]¶
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
]) – Optionally, the past or future covariates used for training.merge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- abstract encode_train_inference(n, target, covariates=None, merge_covariates=True, **kwargs)[source]¶
Each subclass must implement a method to encode the covariates index for training and prediction.
- Parameters
n (
int
) – The forecast horizontarget (
TimeSeries
) – The target TimeSeries used during training and prediction.covariates (
Optional
[TimeSeries
]) – Optionally, the past or future covariates used for training and prediction.merge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- 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)[source]¶
Bases:
CovariatesIndexGenerator
Generates index for future covariates on train and inference datasets.
Attributes
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 methodsgenerate_train_idx()
, andgenerate_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
]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length forTorchForecastingModel
, or to the absolute minimum target lag value abs(min(lags)) forRegressionModel
.output_chunk_length (
Optional
[int
]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for bothTorchForecastingModel
, andRegressionModel
.lags_covariates (
Optional
[List
[int
]]) – 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
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)[source]¶
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- generate_train_idx(target, covariates=None)[source]¶
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
]) – 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 atCovariatesIndexGenerator
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- B in combination with
- class darts.dataprocessing.encoders.encoder_base.PastCovariatesIndexGenerator(input_chunk_length=None, output_chunk_length=None, lags_covariates=None)[source]¶
Bases:
CovariatesIndexGenerator
Generates index for past covariates on train and inference datasets
Attributes
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 methodsgenerate_train_idx()
, andgenerate_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
]) – Optionally, the number of input target time steps per chunk. Only required in scenarios B, C. Corresponds to input_chunk_length forTorchForecastingModel
, or to the absolute minimum target lag value abs(min(lags)) forRegressionModel
.output_chunk_length (
Optional
[int
]) – Optionally, the number of output target time steps per chunk. Only required in scenarios B, and C. Corresponds to output_chunk_length for bothTorchForecastingModel
, andRegressionModel
.lags_covariates (
Optional
[List
[int
]]) – 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
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)[source]¶
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- generate_train_idx(target, covariates=None)[source]¶
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
]) – 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 atCovariatesIndexGenerator
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
]) – 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 atCovariatesIndexGenerator
creation.
- Return type
Tuple
[Union
[DatetimeIndex
,RangeIndex
],Timestamp
]
- B in combination with
- class darts.dataprocessing.encoders.encoder_base.SequentialEncoderTransformer(transformer, transform_mask)[source]¶
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
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 totransform()
must be transformed.
Attributes
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)[source]¶
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)[source]¶
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
Whether the SingleEncoder sub class accepts to be transformed.
Returns the base encoder base component name.
Returns the encoded component names.
The number of components in the SingleEncoder output.
Returns whether the Encoder object has been fitted.
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
Whether the SingleEncoder sub class accepts to be transformed.
Returns the base encoder base component name.
Returns the encoded component names.
The number of components in the SingleEncoder output.
Returns whether the Encoder object has been fitted.
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)[source]¶
Returns encoded index for inference/prediction.
- Parameters
n (
int
) – The forecast horizontarget (
TimeSeries
) – The target TimeSeries used during training or passed to prediction as seriescovariates (
Optional
[TimeSeries
]) – Optionally, the covariates used for prediction: past covariates if self.index_generator is a PastCovariatesIndexGenerator, future covariates if self.index_generator is a FutureCovariatesIndexGeneratormerge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- encode_train(target, covariates=None, merge_covariates=True, **kwargs)[source]¶
Returns encoded index for training.
- Parameters
target (
TimeSeries
) – The target TimeSeries used during training or passed to prediction as seriescovariates (
Optional
[TimeSeries
]) – Optionally, the covariates used for training: past covariates if self.index_generator is a PastCovariatesIndexGenerator, future covariates if self.index_generator is a FutureCovariatesIndexGeneratormerge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- encode_train_inference(n, target, covariates=None, merge_covariates=True, **kwargs)[source]¶
Returns encoded index for inference/prediction.
- Parameters
n (
int
) – The forecast horizontarget (
TimeSeries
) – The target TimeSeries used during training and prediction.covariates (
Optional
[TimeSeries
]) – 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 FutureCovariatesIndexGeneratormerge_covariates (
bool
) – Whether to merge the encoded TimeSeries with covariates.
- Return type
- 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