AdditiveModelForecast

class hana_ml.algorithms.pal.tsa.additive_model_forecast.AdditiveModelForecast(growth=None, logistic_growth_capacity=None, seasonality_mode=None, seasonality=None, num_changepoints=None, changepoint_range=None, regressor=None, changepoints=None, yearly_seasonality=None, weekly_seasonality=None, daily_seasonality=None, seasonality_prior_scale=None, holiday_prior_scale=None, changepoint_prior_scale=None, massive=False, group_params=None)

Additive Model Forecast uses a decomposable time series model with three main components: trend, seasonality, and holidays or event.

Parameters
growth{'linear', 'logistic'}, optional

Specifies a trend, which could be either linear or logistic.

Defaults to 'linear'.

logistic_growth_capacity: float, optional

Specifies the carrying capacity for logistic growth. Mandatory and valid only when growth is 'logistic'.

No default value.

seasonality_mode{'additive', 'multiplicative'}, optional

Mode for seasonality.

Defaults to 'additive'.

seasonalitystr or a list of str, optional

Adds seasonality to the model in a json format, include:

  • NAME

  • PERIOD

  • FOURIER_ORDER

  • PRIOR_SCALE, optional

  • MODE, optional

Each str is in json format such as '{ "NAME": "MONTHLY", "PERIOD":30, "FOURIER_ORDER":5 }'. FOURIER_ORDER determines how quickly the seasonality can change. PRIOR_SCALE controls the amount of regularization. No seasonality will be added to the model if this parameter is not provided.

No default value.

num_changepointsint, optional

The number of potential changepoints. Not effective if changepoints is provided.

Defaults to 25 if not provided.

changepoint_rangefloat, optional

Proportion of history in which trend changepoints will be estimated. Not effective if changepoints is provided.

Defaults to 0.8.

regressora list of str, optional

Specifies the regressor, include:

  • NAME

  • PRIOR_SCALE

  • STANDARDIZE

  • MODE: "additive" or 'multiplicative'.

Each str is json format such as '{ "NAME": "X1", "PRIOR_SCALE":4, "MODE": "additive" }'. PRIOR_SCALE controls for the amount of regularization; STANDARDIZE Specifies whether or not the regressor is standardized.

No default value.

changepointslist of str, optional,

Specifies a list of changepoints in the format of timestamp, such as ['2019-01-01 00:00:00, '2019-02-04 00:00:00']

No default value.

yearly_seasonality{'auto', 'false', 'true'}, optional

Specifies whether or not to fit yearly seasonality.

'false' and 'true' simply corresponds to their logical meaning, while 'auto' means automatically determined from the input data.

Defaults to 'auto'.

weekly_seasonality{'auto', 'false', 'true'}, optional

Specifies whether or not to fit the weekly seasonality.

'auto' means automatically determined from input data.

Defaults to 'auto'.

daily_seasonality{'auto', 'false', 'true'}, optional

Specifies whether or not to fit the daily seasonality.

'auto' means automatically determined from input data.

Defaults to 'auto'.

seasonality_prior_scalefloat, optional

Parameter modulating the strength of the seasonality model.

Defaults to 10.

holiday_prior_scalefloat, optional

Parameter modulating the strength of the holiday components model.

Defaults to 10.

changepoint_prior_scalefloat, optional

Parameter modulating the flexibility of the automatic changepoint selection.

Defaults to 0.05.

massivebool, optional

Specifies whether or not to activate the massive mode.

  • True : massive mode.

  • False : single mode.

For parameter setting in the massive mode, you could use both group_params (please see the example below) or the original parameters. Using original parameters will apply for all groups. However, if you define some parameters of a group, the value of all original parameter setting will be not applicable to such group.

An example is as follows:

In this example, as seasonality_mode is set in group_params for Group_1, parameter setting of changepoint_prior_scale is not applicable to Group_1.

Defaults to False.

group_paramsdict, optional

If the massive mode is activated (massive is True), input data is divided into different groups with different parameters applied.

An example with group_params is as follows:

Valid only when massive is True and defaults to None.

References

Seasonalities in Additive Model Forecast

Examples

Input dataframe:

>>> df_fit.head(5).collect()
        ts         y
2007-12-10  9.590761
2007-12-11  8.519590
2007-12-12  8.183677
2007-12-13  8.072467
2007-12-14  7.893572

Create an Additive Model Forecast model:

>>> amf = additive_model_forecast.AdditiveModelForecast(growth='linear')

Perform fit() on the given data:

>>> amf.fit(data=df_fit)

Output:

>>> amf.model_.collect()
   ROW_INDEX                                      MODEL_CONTENT
0          0  {"GROWTH":"linear","FLOOR":0.0,"SEASONALITY_MO...

Perform predict() on the model:

Input dataframe df_predict:

>>> df_predict.head(5).collect()
            ts    y
0   2008-03-09  0.0
1   2008-03-10  0.0
2   2008-03-11  0.0
3   2008-03-12  0.0
4   2008-03-13  0.0

>>> result = amf.predict(data=df_predict)

Expected output:

>>> result.collect()
            ts      YHAT  YHAT_LOWER  YHAT_UPPER
0   2008-03-09  7.676880    6.930349    8.461546
1   2008-03-10  8.147574    7.387315    8.969112
2   2008-03-11  7.410452    6.630115    8.195562
3   2008-03-12  7.198807    6.412776    7.977391
4   2008-03-13  7.087702    6.310826    7.837083

If you want to see the decomposed result of predict result, you could set show_explainer = True:

>>> result = amf.predict(df_predict,
                         show_explainer=True,
                         decompose_seasonality=False,
                         decompose_holiday=False)

Show the attribute explainer_:

>>> amf.explainer_.head(5).collect()
            ts     TREND                                SEASONAL HOLIDAY EXOGENOUS
0   2008-03-09  7.432172   {"seasonalities":0.24470822257259804}      {}        {}
1   2008-03-10  7.390030     {"seasonalities":0.757544365973254}      {}        {}
2   2008-03-11  7.347887   {"seasonalities":0.06256440574150749}      {}        {}
3   2008-03-12  7.305745  {"seasonalities":-0.10693834906369426}      {}        {}
4   2008-03-13  7.263603  {"seasonalities":-0.17590059499681369}      {}        {}
Attributes
model_DataFrame

Model content.

explainer_DataFrame

The decomposition of trend, seasonal, holiday and exogenous variables.

  • In single mode, only contains value when show_explainer=True in the predict function.

  • In massive mode, this attribute always contains value.

error_msg_DataFrame

Error message. Only valid if massive is True when initializing an 'AdditiveModelForecast' instance.

Methods

build_report()

Generate time series report.

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

Additive model forecast fit function.

generate_html_report([filename])

Display function.

generate_notebook_iframe_report()

Display function.

predict(data[, key, exog, group_key, ...])

Makes time series forecast based on the estimated Additive Model Forecast model.
fit(data, key=None, endog=None, exog=None, holiday=None, group_key=None, group_params=None, categorical_variable=None)

Additive model forecast fit function.

Parameters
dataDataFrame

Input data. The structure is as follows.

  • The first column: index (ID), type TIMESTAMP, SECONDDATE or DATE.

  • The second column: raw data, type INTEGER or DECIMAL(p,s).

  • Other columns: external data, type INTEGER, DOUBLE or DECIMAL(p,s).

keystr, optional

The timestamp column of data. The type of key column is TIMESTAMP, SECONDDATE, or DATE.

In the single mode, defaults to the first column of data if the index column of data is not provided; otherwise, defaults to the index column of data.

In the massive mode, defaults to the first-non group key column of data if the index columns of data is not provided; otherwise, defaults to the second of index columns of data and the first column of index columns is group_key.

endogstr, optional

The endogenous variable, i.e. time series. The type of endog column is INTEGER, DOUBLE, or DECIMAL(p, s).

  • In single mode, defaults to the first non-key column.

  • In massive mode, defaults to the first non group_key, non key column.

exogstr or a list of str, optional

An optional array of exogenous variables. The type of exog column is INTEGER, DOUBLE, or DECIMAL(p, s).

Defaults to None. Please set this parameter explicitly if you have exogenous variables.

holidayDataFrame, optional

Input holiday data. The structure is as follows.

  • 1st column : timestamp/key, TIMESTAMP, SECONDDATE, DATE

  • 2nd column : holiday name, VARCHAR, NVARCHAR

  • 3rd column : lower window of holiday, less than 0, INTEGER, optional

  • 4th column : upper window of holiday, greater than 0, INTEGER, optional

if massive is True, the structure of input holiday data is as follows:

  • 1st column: group_key, INTEGER, VRACHAR or NVARCHAR

  • 2nd column: timestamp/key, TIMESTAMP, SECONDDATE, DATE

  • 3rd column : holiday name, VARCHAR, NVARCHAR

  • 4th column : lower window of holiday, less than 0, INTEGER, optional

  • 3th column : upper window of holiday, greater than 0, INTEGER, optional

Defaults to None.

group_keystr, optional

The column of group_key. Data type can be INT or NVARCHAR/VARCHAR. If data type is INT, only parameters set in the group_params are valid.

This parameter is only valid when self.massive is True.

Defaults to the first column of data if the index columns of data is not provided. Otherwise, defaults to the first column of index columns.

group_paramsdict, optional

If massive mode is activated (massive is True), input data is divided into different groups with different parameters applied.

An example with group_params is as follows:

Valid only when self.massive is True.

Defaults to None.

categorical_variablestr or ist of str, optional

Specifies INTEGER columns specified that should be be treated as categorical.

Other INTEGER columns will be treated as continuous.

Defaults to None.

Returns
A fitted object of "AdditiveModelForecast".
predict(data, key=None, exog=None, group_key=None, group_params=None, logistic_growth_capacity=None, interval_width=None, uncertainty_samples=None, show_explainer=False, decompose_seasonality=None, decompose_holiday=None)

Makes time series forecast based on the estimated Additive Model Forecast model.

Parameters
dataDataFrame, optional

Index and exogenous variables for forecast. The structure is as follows.

  • First column: Index (ID), type TIMESTAMP, SECONDDATE or DATE.

  • Second column: Placeholder column for forecast values, type DOUBLE or DECIMAL(p,s).

  • Other columns : external data, type INTEGER, DOUBLE or DECIMAL(p,s).

if massive is True, the structure of data is as follows:

  • First column: Group_key, type INTEGER, VRACHAR or NVARCHAR.

  • Second column: Index (ID), type TIMESTAMP, SECONDDATE or DATE.

  • Third column : Placeholder column for forecast values, type DOUBLE or DECIMAL(p,s).

  • Other columns: external data, type INTEGER, DOUBLE or DECIMAL(p,s).

keystr, optional

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

In single mode, defaults to the first column of data if the index column of data is not provided. Otherwise, defaults to the index column of data.

In massive mode, defaults to the first-non group key column of data if the index columns of data is not provided; otherwise, defaults to the second of index columns of data and the first column of index columns is group_key.

group_keystr, optional

The column of group_key. Data type can be INT or NVARCHAR/VARCHAR. If data type is INT, only parameters set in the group_params are valid.

This parameter is only valid when massive is True.

Defaults to the first column of data if the index columns of data is not provided. Otherwise, defaults to the first column of index columns.

group_paramsdict, optional

If massive mode is activated (massive is True), input data is divided into different groups with different parameters applied.

An example with group_params is as follows:

Valid only when massive is True and defaults to None.

logistic_growth_capacity: float, optional

Specifies the carrying capacity for logistic growth. Mandatory and valid only when growth is 'logistic'.

Defaults to None.

interval_widthfloat, optional

Width of the uncertainty intervals.

Defaults to 0.8.

uncertainty_samplesint, optional

Number of simulated draws used to estimate uncertainty intervals.

Defaults to 1000.

show_explainerbool, optional

Indicates whether to invoke the AdditiveModelForecast with explanations function in the predict. If true, the contributions of trend, seasonal, holiday and exogenous variables are shown in a attribute called explainer_ of the AdditiveModelForecast instance.

Defaults to False.

decompose_seasonalitybool, optional

Specifies whether or not seasonal component will be decomposed. Valid only when show_explainer is True.

Defaults to False.

decompose_holidaybool, optional

Specifies whether or not holiday component will be decomposed. Valid only when show_explainer is True.

Defaults to False.

Returns
DataFrame 1

Forecasted values, structured as follows:

  • ID, type timestamp.

  • YHAT, type DOUBLE, forecast value.

  • YHAT_LOWER, type DOUBLE, lower bound of confidence region.

  • YHAT_UPPER, type DOUBLE, higher bound of confidence region.

DataFrame 2

The decomposition of trend, seasonal, holiday and exogenous variables. Only available in the massive mode.

DataFrame 3 (optional)

Error message. Only valid if massive is True when initializing an 'AdditiveModelForecast' instance.

build_report()

Generate time series report.

property fit_hdbprocedure

Returns the generated hdbprocedure for fit.

property predict_hdbprocedure

Returns the generated hdbprocedure for predict.

generate_html_report(filename=None)

Display function.

generate_notebook_iframe_report()

Display function.

Inherited Methods from PALBase

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