## Generating Time and Seasonal Features Automatically

### Overview

Inspec has a few functions to help you generate all your time and seasonal features. All you need is 
a pandas datetime Series, and you're good to go. If you have a target vector (y), Inspec can even
select only the relevant ones for you.

### Main Usage

To generate time and seasonal features, simply provide a pandas Series with a datetime dtype to the
`inspec_ai.preprocessing.time_enhancement` function and set the periodicity parameter to `"D"` 
if your series is daily (default value), `"W"` if it is weekly, or `"M"` if it is monthly.

```python
import pandas as pd

from inspec_ai.preprocessing.time_enhancement import time_enhancement

ts = pd.read_csv("a_time_series.csv")
dates = pd.to_datetime(ts["date"])

time_features = time_enhancement(dates=dates, periodicity="D")
```

To only generate time features that have predictive power on your target, you can use
the `inspec_ai.preprocessing.get_predictive_time_fetures` in a similar fashion. Note that 
the feature selection is done using a penalized regression (Lasso), so you can also 
set the L2 regularization parameter `alpha`, which is set to `0.1` by default.

```python
import pandas as pd

from inspec_ai.preprocessing.time_enhancement import get_predictive_time_features

ts = pd.read_csv("a_time_series.csv")
dates = pd.to_datetime(ts["date"])
y = ts["sales"]

predictive_time_features = get_predictive_time_features(dates=dates, y=y, periodicity="D", alpha=0.1)
```

### Custom dates

In addition to features that inspec generates for you (see section below), you can also provide
your own custom dates to be added as features using the `custom_dates` argument. The custom dates
can either be `datetime.datetime` objects or `str` with the `"AAAA-MM-DD"` format. Lists of dates are
also accepted for recurring events.


Note that **the custom dates are only available for daily periodicity series**.
```python
import pandas as pd

from inspec_ai.preprocessing.time_enhancement import time_enhancement

custom_dates = {
    "Festival de la langoustine": "2020-09-02",
    "Jour de la crevette": ["2020-05-12", "2021-05-15"]
}

ts = pd.read_csv("a_time_series.csv")
dates = pd.to_datetime(ts["date"])

time_features = time_enhancement(dates=dates, periodicity="D", custom_dates=custom_dates)
```

### Included time and seasonal features
The features that are automatically generated by `inspec_ai.preprocessing.time_enhancement`, and considered
by `inspec_ai.preprocessing.get_predictive_time_fetures` are the following:


|                        | Daily | Weekly | Monthly  |
|        -----------     |  ---  |   ---  |  ---     |
| week dummies           |  ✅   |  ✅   |    ❌    |
| month dummies          |  ✅   |  ✅   |    ❌    |
| day of week dummies    |  ✅   |  ❌   |    ❌    |
| holiday dummies        |  ✅   |  ❌   |    ❌    |
| custom dates           |  ✅   |  ❌   |    ❌    |
| trigonometric features |  ✅   |  ✅   |    ✅    |

The included holiday dummies are the Canadian (Quebec) dummies from the `holidays` python package.
