TimeMurmur 0.1.3

Time series forecasting at scale with 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)