Lacking documentation for gluonts.time_feature.holiday module

adarwade1 commented 3 years ago

Description

Gluonts.time_feature.holiday.distance_to_holiday(holiday)

holiday parameter : What values to be pass. It gives error in case

holiday =[CHRISTMAS_DAY, CHRISTMAS_EVE]

there is no attribute date.

holiday.date()

To Reproduce

(Please provide minimal example of code snippet that reproduces the error. For existing examples, please provide link.)

put code here

Error message or code output

(Paste the complete error message, including stack trace, or the undesired output that the above snippet produces.)

put error or undesired output here

Environment

Operating system:
Python version:
GluonTS version:
MXNet version:

(Add as much information about your environment as possible, e.g. dependencies versions.)

lostella commented 3 years ago

Hi @adarwade1 I removed the "bug" label since I believe that this is more of a documentation issue. I will open a separate issue for that, also concerning the fact that this part of the API is not 100% consistent with other time features.

The easiest way for you to compute those distances is using the SpecialDateFeatureSet class from that module. For example, the following will compute features related to Christmas day:

import pandas as pd

index = pd.date_range(start="2020-12-15 00:00:00", periods=30, freq="D")

from gluonts.time_feature.holiday import CHRISTMAS_DAY, SpecialDateFeatureSet
from gluonts.time_feature.holiday import indicator, exponential_kernel, squared_exponential_kernel

kernel = lambda x: x

feature_set = SpecialDateFeatureSet(
    feature_names=[CHRISTMAS_DAY],
    kernel_function=kernel
)

print(feature_set(index))

which outputs

[[-10  -9  -8  -7  -6  -5  -4  -3  -2  -1   0   1   2   3   4   5   6   7
    8   9  10  11  12  13  14  15  16  17  18  19]]

(linear distance from the specified date). Here we used the "identity" kernel: changing it to other functions will yield different functions of such distance. For example:

With kernel = indicator

[[0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 1. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0. 0.
  0. 0. 0. 0. 0. 0.]]

With kernel = exponential_kernel()

[[4.53999298e-05 1.23409804e-04 3.35462628e-04 9.11881966e-04
  2.47875218e-03 6.73794700e-03 1.83156389e-02 4.97870684e-02
  1.35335283e-01 3.67879441e-01 1.00000000e+00 3.67879441e-01
  1.35335283e-01 4.97870684e-02 1.83156389e-02 6.73794700e-03
  2.47875218e-03 9.11881966e-04 3.35462628e-04 1.23409804e-04
  4.53999298e-05 1.67017008e-05 6.14421235e-06 2.26032941e-06
  8.31528719e-07 3.05902321e-07 1.12535175e-07 4.13993772e-08
  1.52299797e-08 5.60279644e-09]]

With kernel = squared_exponential_kernel()

[[0.00000000e+00 0.00000000e+00 0.00000000e+00 0.00000000e+00
  0.00000000e+00 0.00000000e+00 1.12535175e-07 1.23409804e-04
  1.83156389e-02 3.67879441e-01 1.00000000e+00 3.67879441e-01
  1.83156389e-02 1.23409804e-04 1.12535175e-07 0.00000000e+00
  0.00000000e+00 0.00000000e+00 0.00000000e+00 0.00000000e+00
  0.00000000e+00 0.00000000e+00 0.00000000e+00 0.00000000e+00
  0.00000000e+00 0.00000000e+00 0.00000000e+00 0.00000000e+00
  0.00000000e+00 0.00000000e+00]]

You can also play with the parameters of the provided kernels to adapt the features to your needs, or to any custom normalization/post-processing on the resulting arrays.

adarwade1 commented 3 years ago

Hi Lorenzo, Many Thanks for details.

awslabs / gluonts