BSTS

class hana_ml.algorithms.pal.tsa.bsts.BSTS(burn=None, niter=None, seasonal_period=None, expected_model_size=None, seed=None)

Bayesian structural time series (BSTS) model is for time series analysis including forecasting, decomposition and feature selection. Compared with ARIMA and Additive Model Time Series Analysis, BSTS is superior because it can deal with much larger scale exogenous data and interpret more precisely on forecasting. Besides, BSTS can sort the exogenous data by their importance to the target time series, which provides users with another perspective to dive into the data.

Basically, let \(y_t\) denote the observed value at time t in a real-valued time-series, a generic structural time series model can be described by a pair of equations relating \(y_t\) to a vector of latent state variables \(\alpha_t\) as follows:

  • \(y_t = Z_t^T\alpha_t + \epsilon_t, \epsilon_t\sim N(0, H_t)\)

  • \(\alpha_t = T_t\alpha_t + R_t\eta_t, \eta_t \sim N(0, Q_t)\)

In this class, a special structural time-series model is considered, with system equation stated as follows:

  • \(y_t = \mu_t + \tau_t + \beta^T \bf{x}_t + \epsilon_t\),

  • \(\mu_t = \mu_{t-1} + \delta_t + u_t\),

  • \(\delta_t = \delta_{t-1} + v_t\),

  • \(\tau_t = -\sum_{s=1}^{S-1}\tau_{t-s} + w_t\),

where \(\mu_t, \delta_t, \tau_t\) and \(\beta^T\bf{x}_t\) are the trend, slope of trend, seasonal(with period S) and regression components w.r.t. contemporaneous data, respectively, \(\epsilon_t, u_t, v_t\) and \(w_t\) are independent Gaussian random variables.

BSTS can be seen as a combination of three Bayesian methods altogether - Kalman filter, spike-and-slab regression and Bayesian model averaging. In particular, samples of model parameters are drawn from its posterior distributions using MCMC.

Parameters:
burnfloat, optional

Specifies the ratio of total MCMC draws that are neglected from the beginning. Ranging from 0 to 1. In other words, only the tail 1-burn portion of the total MCMC draw is kept(in the model) for prediction.

Defaults to 0.5.

niterint, optional

Specifies the total number of MCMC draws.

Defaults to 1000.

seasonal_periodint, optional

Specifies the value of seasonal period.

  • Negative value : Period determined automatically

  • 0 or 1 : Target time-series assumed non-seasonal

  • 2 or larger : The specified value of seasonal period

Defaults to -1, i.e. determined automatically.

expected_model_sizeint, optional

Specifies the number of contemporaneous data that are expected to be included in the model.

Defaults to half of the number of contemporaneous data columns.

Examples

>>> data.collect()
    TIME_STAMP  TARGET_SERIES  FEATURE_01  FEATURE_02  ...  FEATURE_07  FEATURE_08  FEATURE_09  FEATURE_10
0            0          2.536       1.488      -0.561  ...       0.300       1.750       0.498       0.073
1            1          0.882       1.100      -0.992  ...       0.180      -0.011       0.264       0.584
...
49          49         -0.144      -0.120      -0.496  ...      -0.856      -1.313      -1.161       0.150

>>> bt = BSTS(burn=0.6, expected_model_size=2, niter=2000, seasonal_period=12, seed=1)
>>> bt.fit(data=df, key='TIME_STAMP')
>>> bt.stats_.collect()
>>> bt.stats_.collect()
    DATA_NAME  INCLUSION_PROB  AVG_COEFF
0  FEATURE_08         0.48500   0.173861
1  FEATURE_01         0.40250   0.437837
...
9  FEATURE_05         0.08750   0.021849

>>> df_pred.collect()
   TIME_STAMP  FEATURE_01  FEATURE_02  FEATURE_03  ...  FEATURE_07  FEATURE_08  FEATURE_09  FEATURE_10
0          50       0.471      -0.660      -0.086  ...      -1.107      -0.559      -1.404      -1.646
1          51       0.872       0.062       0.481  ...      -0.729       0.894      -0.754       1.107
...
9          59      -0.611      -1.163       0.186  ...      -0.976      -0.576      -0.927      -1.577
>>> forecast, _ = bt.predict(data=df_pred, key='TIME_STAMP')
>>> forecast.collect()
   TIME_STAMP  FORECAST        SE  LOWER_80  UPPER_80  LOWER_95  UPPER_95
0          50  0.143151  0.591231 -0.614542  0.900844 -1.015640  1.301943
1          51  0.469405  0.765558 -0.511697  1.450508 -1.031060  1.969871
...
9          59  0.339182  2.763764 -3.202725  3.881089 -5.077696  5.756059
Attributes:
stats_DataFrame

Related statistics on the inclusion of contemporaneous data w.r.t. the target time-series, structured as follows:

  • 1st column : DATA_NAME, type NVARCHAR or NVARCHAR, indicating the (column) name of contemporaneous data.

  • 2nd column : INCLUSION_PROB, type DOUBLE, indicating the inclusion probability of each contemporaneous data column.

  • 3rd column : AVG_COEFF, type DOUBLE, indicating the average value of coefficients for each contemporaneous data column if included in the model.

decompose_DataFrame

Decomposed components of the target time-series, structured as follows:

  • 1st column : TIME_STAMP, type INTEGER, representing the order of time-series and is sorted ascendingly.

  • 2nd column : TREND, type DOUBLE, representing the trend component.

  • 3rd column : SEASONAL, type DOUBLE, representing the seasonal component.

  • 4th column : REGRESSION, type DOUBLE, representing the regression component w.r.t. contemporaneous data.

  • 5th column : RANDOM, type DOUBLE, representing the random component.

model_DataFrame

DataFrame containing the retained tail MCMC samples in a JSON string, structured as follows:

  • 1st column : ROW_INDEX, type INTEGER, indicating the ID of current row.

  • 2nd column : MODEL_CONTENT, type NVARCHAR, JSON string.

permutation_importance_DataFrame

The importance of exogenous variables as determined by permutation importance analysis. The attribute only appear when invoking get_permutation_importance() function after a trained model is obtained, structured as follows:

  • 1st column : PAIR, measure name.

  • 2nd column : NAME, exogenous regressor name.

  • 3rd column : VALUE, the importance of the exogenous regressor.

Methods

fit(data[, key, endog, exog])

Fit the model to the training dataset.

get_permutation_importance(data[, model, ...])

Please see Permutation Feature Importance for Time Series for details.

predict([data, key, exog, horizon])

Generates time series forecasts based on the fitted model.
fit(data, key=None, endog=None, exog=None)

Fit the model to the training dataset.

Parameters:
dataDataFrame

Input data for BSTS, inclusive of timestamp, target series and contemporaneous data columns.

keystr, optional

The timestamp column of data. The type of key column should be INTEGER, TIMESTAMP, DATE or SECONDDATE.

Defaults to index column of data is data is indexed by a single column, otherwise it is mandatory.

endogstr, optional

The endogenous variable, i.e. the target time-series. The type of endog column could be INTEGER, DOUBLE or DECIMAL(p,s).

Defaults to the first non-key column of data.

exogstr or a list of str, optional

An optional array of exogenous variables, i.e. contemporaneous data columns. The type of exog column could be INTEGER, DOUBLE or DECIMAL(p,s).

Defaults to all non-key, non-endog columns in data.

Returns:
A fitted object of class "BSTS".
predict(data=None, key=None, exog=None, horizon=None)

Generates time series forecasts based on the fitted model.

Parameters:
dataDataFrame, optional

Index and contemporaneous data for BSTS prediction.

Required only if contemporaneous data is available in the training phase.

keystr, optional

The timestamp column of data, should be of type INTEGER, TIMESTAMP, DATE or SECONDDATE.

Effective only when data is not None.

Defaults to the index of data if data is indexed by a single column, otherwise it is mandatory.

exogstr of list or str, optional

An optional array of exogenous variables, i.e. contemporaneous data columns. The type of exog column could be INTEGER, DOUBLE or DECIMAL(p,s).

Effective only when data is not None.

Defaults to all non-key columns in data.

horizonint, optional

Number of predictions for future observations.

Valid only when data is None.

Defaults to 1.

Returns:
DataFrame 1

DataFrame containing the forecast values and other related statistics(like standard error estimation, upper/lower quantiles).

DataFrame 2

DataFrame containing the trend/seasonal/regression components w.r.t. the forecast values.

get_permutation_importance(data, model=None, key=None, endog=None, exog=None, repeat_time=None, random_state=None, thread_ratio=None, partition_ratio=None, regressor_top_k=None, accuracy_measure=None, ignore_zero=None)

Please see Permutation Feature Importance for Time Series for details.

Inherited Methods from PALBase

Besides those methods mentioned above, the BSTS class also inherits methods from PALBase class, please refer to PAL Base for more details.