TimeMurmur 0.1.3
Time series forecasting at scale with LightGBM
Keywords: forecasting,time series,lightgbm

# TimeMurmur
Requires the forecast period is the same for all time series.
## Quickstart
```
pip install TimeMurmur
```
Get example dataset and ensure the date column is Datetime:
```
from TimeMurmur.utils.utility_functions import get_data
train_df = get_data()
train_df['Datetime'] = pd.to_datetime(train_df['Datetime'])
```
This dataset is a subset of the weekly data from M4, it includes the required ID, Datetime, and History columns.

The most basic model you can fit is:
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W')
predicted = murmur.predict(20)
```
These parameters are required, the freq is 'W' for Weekly following standard frequency nomenclature.
You can take a look with the helper function:
```
for i in range(3):
    murmur.plot(fitted, predicted=predicted, murmur_id=i)
```
## Adding AR Lags
In order to do recursive forecasting utilizing past values, just pass a list of lags you want to the ar parameter:
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W',
                    n_basis=[10],
                    ar=[1,2,3,4])
predicted = murmur.predict(20)
```
Here we use a linear basis function with 4 ar lags passed as a list.
## Adding Seasonality
Seasonality works similar to the ar lags. We can pass multiple seasonal periods in a list if we have multiple seasonalities to account for.
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W',
                    n_basis=[10],
                    ar=[1,2,3,4],
                    seasonal_period=[4,52])
predicted = murmur.predict(20)
```
## LightGBM Parameters
You can pass a few of the most influential LightGBM parameters to fit such as `num_iterations` and `num_leaves`:
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W',
                    n_basis=[10],
                    ar=[1,2,3,4],
                    seasonal_period=[4,52],
                    num_iterations=100,
                    learning_rate=.1,
                    num_leaves=31)
predicted = murmur.predict(20)
```
## Fitting with category exogenous.
This is a 'ID' axis variable since it never changes across time only across IDs. Since it is a string we pass it to 'categorical_columns' as well.
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W',
                    n_basis=[10],
                    ar=[1,2,3,4],
                    seasonal_period=[4,52],
                    num_iterations=100,
                    learning_rate=.1,
                    num_leaves=31,
                    categorical_columns=['category'],
                    id_feature_columns=['category'])
predicted = murmur.predict(20)
```
## Fitting Quantiles
To fit quantiles pass `quantile` for `objective` and the desired quantile percentage to `alpha`.
```
murmur = Murmur(floor=0)
fitted = murmur.fit(train_df,
                    target_column='History',
                    id_column='ID',
                    date_column='Datetime',
                    freq='W',
                    n_basis=[10],
                    ar=[1,2,3,4],
                    seasonal_period=[4,52],
                    num_iterations=100,
                    learning_rate=.1,
                    num_leaves=31,
                    objective='quantile',
                    alpha=.9)
predicted = murmur.predict(20)
```

## Explanations with Shapley

```
#get shapley values of predictions
predicted_shap_vals = murmur.explain_predictions(predicted)
fitted_shap_vals = murmur.explain_fitted(fitted)
#plot using shapley values
murmur.plot_explanations(fitted_shap_vals=fitted_shap_vals,
                         predicted_shap_vals=predicted_shap_vals,
                         murmur_id=0)
```