Time Axes Encoders

Encoders can generate past and/or future covariate series by encoding the index of a TimeSeries series. Each encoder class has an encode_train() and encode_inference() to generate the encodings for training and inference.

The encoders extract the index either from the target series or optional additional past/future covariates. If additional covariates are supplied to encode_train() or encode_inference(), the time index of those covariates are used for the encodings. This means that the input covariates must meet the same model-specific requirements as wihtout encoders.

There are two main types of encoder classes: SingleEncoder and SequentialEncoder.

  • SingleEncoder

    The SingleEncoder classes carry the encoder logic for past and future covariates, and training and inference datasets. They can be used as stand-alone encoders.

    Each SingleEncoder has a dedicated subclass for generating past or future covariates. The naming convention is {X}{SingleEncoder} where {X} is one of (Past, Future) and {SingleEncoder} is one of the SingleEncoder classes described in the next section. An example:

    encoder = PastDatetimeAttributeEncoder(input_chunk_length=24,
                                       output_chunk_length=12,
                                       attribute='month')

past_covariates_train = encoder.encode_train(target=target,
                                             covariate=optional_past_covariates)
past_covariates_inf = encoder.encode_inference(n=12,
                                               target=target,
                                               covariate=optional_past_covariates)
  • SequentialEncoder

    Stores and controls multiple SingleEncoders for both past and/or future covariates all under one hood. It provides the same functionality as SingleEncoders (encode_train() and encode_inference()). It can be used both as stand-alone or as an all-in-one solution with Darts’ TorchForecastingModel models through optional parameter add_encoders:

    model = SomeTorchForecastingModel(..., add_encoders={...})

    If used at model creation, the SequentialEncoder will handle all past and future encoders autonomously. The requirements for model parameter add_encoders are described in the next section or in SequentialEncoder.

SingleEncoder

The SingleEncoders from {X}{SingleEncoder} are:

  • DatetimeAttributeEncoder

    Adds scalar pd.DatatimeIndex attribute information derived from series.time_index. Requires series to have a pd.DatetimeIndex.

    attribute

    An attribute of pd.DatetimeIndex: see all available attributes in https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex.

  • CyclicTemporalEncoder

    Adds cyclic pd.DatetimeIndex attribute information deriveed from series.time_index. Adds 2 columns, corresponding to sin and cos encodings, to uniquely describe the underlying attribute. Requires series to have a pd.DatetimeIndex.

    attribute

    An attribute of pd.DatetimeIndex that follows a cyclic pattern. One of (‘month’, ‘day’, ‘weekday’, ‘dayofweek’, ‘day_of_week’, ‘hour’, ‘minute’, ‘second’, ‘microsecond’, ‘nanosecond’, ‘quarter’, ‘dayofyear’, ‘day_of_year’, ‘week’, ‘weekofyear’, ‘week_of_year’).

  • IntegerIndexEncoder

    Adds absolute or relative index positions as integer values (positions) derived from series time index. series can either have a pd.DatetimeIndex or an integer index.

    attribute

    Either ‘absolute’ or ‘relative’. ‘absolute’ will generate position values ranging from 0 to inf where 0 is set at the start of series. ‘relative’ will generate position values relative to the forecasting/prediction point. Values range from -inf to inf where 0 is set at the forecasting point.

  • CallableIndexEncoder

    Applies a user-defined callable to encode series’ index. series can either have a pd.DatetimeIndex or an integer index.

    attribute

    a callable/function to encode the index. For series with a pd.DatetimeIndex: lambda index: (index.year - 1950) / 50. For series with an integer index: lambda index: index / 50

SequentialEncoder

The SequentialEncoder combines the logic of all SingleEncoders from above and has additional benefits:

  • use multiple encoders at once

  • generate multiple attribute encodings at once

  • generate both past and future at once

  • supports transformers (Scaler)

  • easy to use with TorchForecastingModels

The model parameter add_encoders must be a Dict following of this convention:

  • outer keys: SingleEncoder and Transformer tags:

    • ‘datetime_attribute’ for DatetimeAttributeEncoder

    • ‘cyclic’ for CyclicEncoder

    • ‘position’ for IntegerIndexEncoder

    • ‘custom’ for CallableIndexEncoder

    • ‘transformer’ for a transformer

  • inner keys: covariate type

    • ‘past’ for past covariates

    • ‘future’ for future covariates

    • (do not specify for ‘transformer’)

  • inner key values:

    • list of attributes for SingleEncoder

    • transformer object for ‘transformer’

Below is an example that illustrates a valid add_encoders dict for hourly data and how it can be used with a TorchForecastingModel (this is only meant to illustrate many features at once).

add_encoders = {
    'cyclic': {'future': ['month']},
    'datetime_attribute': {'future': ['hour', 'dayofweek']},
    'position': {'past': ['absolute'], 'future': ['relative']},
    'custom': {'past': [lambda idx: (idx.year - 1950) / 50]},
    'transformer': Scaler()
}

model = SomeTorchForecastingModel(..., add_encoders=add_encoders)
class darts.utils.data.encoders.CallableIndexEncoder(index_generator, attribute)[source]

Bases: darts.utils.data.encoder_base.SingleEncoder

CallableIndexEncoder: Applies a user-defined callable to encode the underlying index for past and future covariates.

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • index_generator (CovariateIndexGenerator) – An instance of CovariateIndexGenerator with methods generate_train_series() and generate_inference_series(). Used to generate the index for encoders.

  • attribute (Callable) – A callable that takes an index index of type (pd.DatetimeIndex, pd.RangeIndex) as input and returns a np.ndarray of shape (len(index),). An example for a correct attribute for index of type pd.DatetimeIndex: attribute = lambda index: (index.year - 1950) / 50. And for pd.RangeIndex: attribute = lambda index: (index - 1950) / 50

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CallableIndexEncoder accepts transformations.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.CyclicTemporalEncoder(index_generator, attribute)[source]

Bases: darts.utils.data.encoder_base.SingleEncoder

Cyclic index encoding for TimeSeries that have a time index of type pd.DatetimeIndex.

Parameters

Attributes

accept_transformer

CyclicTemporalEncoder should not be transformed.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CyclicTemporalEncoder should not be transformed. Returns two elements for sine and cosine waves.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.DatetimeAttributeEncoder(index_generator, attribute)[source]

Bases: darts.utils.data.encoder_base.SingleEncoder

DatetimeAttributeEncoder: Adds pd.DatatimeIndex attribute information derived from the index as scalars. Requires the underlying TimeSeries to have a pd.DatetimeIndex

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

DatetimeAttributeEncoder accepts transformations

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.FutureCallableIndexEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.CallableIndexEncoder

IntegerIndexEncoder: Adds integer index value (position) for future covariates derived from the underlying TimeSeries’ time index.

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • input_chunk_length (int) – The length of the emitted past series.

  • output_chunk_length (int) – The length of the emitted future series.

  • attribute (Union[str, Callable]) – A callable that takes an index index of type (pd.DatetimeIndex, pd.RangeIndex) as input and returns a np.ndarray of shape (len(index),). An example for a correct attribute for index of type pd.DatetimeIndex: attribute = lambda index: (index.year - 1950) / 50. And for pd.RangeIndex: attribute = lambda index: (index - 1950) / 50

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CallableIndexEncoder accepts transformations.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.FutureCyclicEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.CyclicTemporalEncoder

Cyclic encoder for future covariates.

Attributes

accept_transformer

CyclicTemporalEncoder should not be transformed.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

Attributes

accept_transformer

CyclicTemporalEncoder should not be transformed.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CyclicTemporalEncoder should not be transformed. Returns two elements for sine and cosine waves.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.FutureDatetimeAttributeEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.DatetimeAttributeEncoder

Datetime attribute encoder for future covariates.

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

DatetimeAttributeEncoder accepts transformations

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.FutureIntegerIndexEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.IntegerIndexEncoder

IntegerIndexEncoder: Adds integer index value (position) for future covariates derived from the underlying TimeSeries’ time index.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • input_chunk_length (int) – The length of the emitted past series.

  • output_chunk_length (int) – The length of the emitted future series.

  • attribute (str) – Either ‘absolute’ or ‘relative’. If ‘absolute’, the generated encoded values will range from (0, inf) and the train target series will be used as a reference to set the 0-index. If ‘relative’, the generated encoded values will range from (-inf, inf) and the train target series end time will be used as a reference to evaluate the relative index positions.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

IntegerIndexEncoder accepts transformations. Note that transforming ‘relative’ IntegerIndexEncoder will return an ‘absolute’ index.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.IntegerIndexEncoder(index_generator, attribute)[source]

Bases: darts.utils.data.encoder_base.SingleEncoder

IntegerIndexEncoder: Adds integer index value (position) derived from the underlying TimeSeries’ time index for past and future covariates.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • index_generator (CovariateIndexGenerator) – An instance of CovariateIndexGenerator with methods generate_train_series() and generate_inference_series(). Used to generate the index for encoders.

  • attribute (str) – Either ‘absolute’ or ‘relative’. If ‘absolute’, the generated encoded values will range from (0, inf) and the train target series will be used as a reference to set the 0-index. If ‘relative’, the generated encoded values will range from (-inf, inf) and the train target series end time will be used as a reference to evaluate the relative index positions.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

IntegerIndexEncoder accepts transformations. Note that transforming ‘relative’ IntegerIndexEncoder will return an ‘absolute’ index.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.PastCallableIndexEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.CallableIndexEncoder

IntegerIndexEncoder: Adds integer index value (position) for past covariates derived from the underlying TimeSeries’ time index.

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • input_chunk_length (int) – The length of the emitted past series.

  • output_chunk_length (int) – The length of the emitted future series.

  • attribute (Union[str, Callable]) – A callable that takes an index index of type (pd.DatetimeIndex, pd.RangeIndex) as input and returns a np.ndarray of shape (len(index),). An example for a correct attribute for index of type pd.DatetimeIndex: attribute = lambda index: (index.year - 1950) / 50. And for pd.RangeIndex: attribute = lambda index: (index - 1950) / 50

Attributes

accept_transformer

CallableIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CallableIndexEncoder accepts transformations.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.PastCyclicEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.CyclicTemporalEncoder

Cyclic encoder for past covariates.

Attributes

accept_transformer

CyclicTemporalEncoder should not be transformed.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

Attributes

accept_transformer

CyclicTemporalEncoder should not be transformed.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

CyclicTemporalEncoder should not be transformed. Returns two elements for sine and cosine waves.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.PastDatetimeAttributeEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.DatetimeAttributeEncoder

Datetime attribute encoder for past covariates.

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

Attributes

accept_transformer

DatetimeAttributeEncoder accepts transformations

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

DatetimeAttributeEncoder accepts transformations

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.PastIntegerIndexEncoder(input_chunk_length, output_chunk_length, attribute)[source]

Bases: darts.utils.data.encoders.IntegerIndexEncoder

IntegerIndexEncoder: Adds integer index value (position) for past covariates derived from the underlying TimeSeries’ time index.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
Parameters

  • input_chunk_length (int) – The length of the emitted past series.

  • output_chunk_length (int) – The length of the emitted future series.

  • attribute (str) – Either ‘absolute’ or ‘relative’. If ‘absolute’, the generated encoded values will range from (0, inf) and the train target series will be used as a reference to set the 0-index. If ‘relative’, the generated encoded values will range from (-inf, inf) and the train target series end time will be used as a reference to evaluate the relative index positions.

Attributes

accept_transformer

IntegerIndexEncoder accepts transformations.

Methods

encode_inference(n, target[, covariate, ...])

Returns encoded index for inference/prediction.

encode_train(target[, covariate, ...])

Returns encoded index for training.
property accept_transformer: List[bool]

IntegerIndexEncoder accepts transformations. Note that transforming ‘relative’ IntegerIndexEncoder will return an ‘absolute’ index.

Return type

List[bool]

encode_inference(n, target, covariate=None, merge_covariate=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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for prediction: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

encode_train(target, covariate=None, merge_covariate=True, **kwargs)

Returns encoded index for training.

Parameters

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

  • covariate (Optional[TimeSeries]) – Optionally, the covariate used for training: past covariate if self.index_generator is instance of PastCovariateIndexGenerator, future covariate if self.index_generator is instance of FutureCovariateIndexGenerator

  • merge_covariate (bool) – Whether or not to merge the encoded TimeSeries with covariate.

Return type

TimeSeries

class darts.utils.data.encoders.SequentialEncoder(add_encoders, input_chunk_length, output_chunk_length, takes_past_covariates=False, takes_future_covariates=False)[source]

Bases: darts.utils.data.encoder_base.Encoder

A SequentialEncoder object can store and control multiple past and future covariate encoders at once. It provides the same functionality as single encoders (encode_train() and encode_inference()).

Attributes

encoder_map

Mapping between encoder identifier string (from parameters at model creations) and the corresponding future or past covariate encoder

future_encoders

Returns the future covariate encoder objects

future_transformer

Returns the future transformer object

past_encoders

Returns the past covariate encoder objects

past_transformer

Returns the past transformer object

Methods

encode_inference(n, target[, ...])

Returns encoded index for all past and/or future covariates for inference/prediction.

encode_train(target[, past_covariate, ...])

Returns encoded index for all past and/or future covariates for training.

SequentialEncoder automatically creates encoder objects from parameter add_encoders used when creating a TorchForecastingModel.

  • Only kwarg add_encoders of type Optional[Dict] will be used to extract the encoders. For example: model = MyModel(…, add_encoders={…}, …)

The add_encoders dict must follow this convention:

{encoder keyword: {temporal keyword: List[attributes]}, …, transformer keyword: transformer object}

Supported encoder keywords:

‘cyclic’ for cyclic temporal encoder. See the docs CyclicTemporalEncoder; ‘datetime_attribute’ for adding scalar information of pd.DatetimeIndex attribute. See the docs DatetimeAttributeEncoder ‘position’ for integer index position encoder. See the docs IntegerIndexEncoder; ‘custom’ for encoding index with custom callables (functions). See the docs CallableIndexEncoder;

Supported temporal keywords:

‘past’ for adding encoding as past covariates ‘future’ for adding encoding as future covariates

Supported attributes:

for attributes read the referred docs for the corresponding encoder from above

Supported transformers:

a transformer can be added with transformer keyword ‘transformer’. The transformer object must be an instance of Darts’ FittableDataTransformer such as Scaler() or BoxCox(). The transformers will be fitted on the training dataset when calling calling model.fit(). The training, validation and inference datasets are then transformed equally.

An example of a valid add_encoders dict for hourly data:

from darts.dataprocessing.transformers import Scaler
add_encoders={
    'cyclic': {'future': ['month']},
    'datetime_attribute': {'past': ['hour'], 'future': ['year', 'dayofweek']},
    'position': {'past': ['absolute'], 'future': ['relative']},
    'custom': {'past': [lambda idx: (idx.year - 1950) / 50]},
    'transformer': Scaler()
}

Tuples of (encoder_id, attribute) are extracted from add_encoders to instantiate the SingleEncoder objects:

  • The encoder_id is extracted as follows:

    str(encoder_kw) + str(temporal_kw) -> ‘cyclic’ + ‘past’ -> encoder_id = ‘cyclic_past’ The encoder_id is used to map the parameters with the corresponding SingleEncoder objects.

  • The attribute is extracted from the values given by values under temporal_kw

    attribute = ‘month’ … The attribute tells the SingleEncoder which attribute of the index to encode

New encoders can be added by appending them to the mapping property SequentialEncoder.encoder_map()

Parameters

  • add_encoders (Dict) – The parameters used at TorchForecastingModel model creation.

  • input_chunk_length (int) – The length of the emitted past series.

  • output_chunk_length (int) – The length of the emitted future series.

  • takes_past_covariates (bool) – Whether or not the TrainingDataset takes past covariates

  • takes_future_covariates (bool) – Whether or not the TrainingDataset takes past covariates

Attributes

encoder_map

Mapping between encoder identifier string (from parameters at model creations) and the corresponding future or past covariate encoder

future_encoders

Returns the future covariate encoder objects

future_transformer

Returns the future transformer object

past_encoders

Returns the past covariate encoder objects

past_transformer

Returns the past transformer object

Methods

encode_inference(n, target[, ...])

Returns encoded index for all past and/or future covariates for inference/prediction.

encode_train(target[, past_covariate, ...])

Returns encoded index for all past and/or future covariates for training.
encode_inference(n, target, past_covariate=None, future_covariate=None, encode_past=True, encode_future=True)[source]

Returns encoded index for all past and/or future covariates for inference/prediction. Which covariates are generated depends on the parameters used at model creation.

Parameters

  • n (int) – The forecast horizon

  • target (Union[TimeSeries, Sequence[TimeSeries]]) – The target TimeSeries used during training or passed to prediction as series

  • past_covariate (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past covariates used for training.

  • future_covariate (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future covariates used for training.

  • encode_past (bool) – Whether or not to apply encoders for past covariates

  • encode_future (bool) – Whether or not to apply encoders for future covariates

Returns

The past_covariate and/or future_covariate for prediction/inference including the encodings. If input {x}_covariate is None and no {x}_encoders are given, will return None for the {x}_covariate.

Return type

Tuple[past_covariate, future_covariate]

encode_train(target, past_covariate=None, future_covariate=None, encode_past=True, encode_future=True)[source]

Returns encoded index for all past and/or future covariates for training. Which covariates are generated depends on the parameters used at model creation.

Parameters

  • target (Union[TimeSeries, Sequence[TimeSeries]]) – The target TimeSeries used during training or passed to prediction as series

  • past_covariate (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past covariates used for training.

  • future_covariate (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future covariates used for training.

  • encode_past (bool) – Whether or not to apply encoders for past covariates

  • encode_future (bool) – Whether or not to apply encoders for future covariates

Returns

The past_covariate and/or future_covariate for training including the encodings. If input {x}_covariate is None and no {x}_encoders are given, will return None for the {x}_covariate.

Return type

Tuple[past_covariate, future_covariate]

Raises

Warning – If model was created with add_encoders and there is suspicion of lazy loading. The encodings/covariates are generated eagerly before starting training for all individual targets and loaded into memory. Depending on the size of target data, this can create memory issues. In case this applies, consider setting add_encoders=None at model creation and build your encodings covariates manually for lazy loading.

property encoder_map: Dict

Mapping between encoder identifier string (from parameters at model creations) and the corresponding future or past covariate encoder

Return type

Dict

property future_encoders: List[darts.utils.data.encoder_base.SingleEncoder]

Returns the future covariate encoder objects

Return type

List[SingleEncoder]

property future_transformer: darts.utils.data.encoder_base.SequentialEncoderTransformer

Returns the future transformer object

Return type

SequentialEncoderTransformer

property past_encoders: List[darts.utils.data.encoder_base.SingleEncoder]

Returns the past covariate encoder objects

Return type

List[SingleEncoder]

property past_transformer: darts.utils.data.encoder_base.SequentialEncoderTransformer

Returns the past transformer object

Return type

SequentialEncoderTransformer

previous

Encoder Base Classes

next

Horizon-Based Training Dataset