hanaml.AdditiveModelForecast is a R wrapper for SAP HANA PAL additive model forecast algorithm.

hanaml.AdditiveModelForecast(
  data = NULL,
  key = NULL,
  endog = NULL,
  exog = NULL,
  holiday = NULL,
  growth = NULL,
  logistic.growth.capacity = NULL,
  seasonality.mode = NULL,
  seasonality = NULL,
  num.changepoints = NULL,
  changepoint.range = NULL,
  regressor = NULL,
  changepoints = NULL,
  yearly.seasonality = NULL,
  weekly.seasonality = NULL,
  daily.seasonality = NULL,
  seasonality.prior.scale = NULL,
  holiday.prior.scale = NULL,
  changepoint.prior.scale = NULL,
  categorical.variable = NULL,
  massive = FALSE,
  group.key = NULL,
  group.params = NULL
)

Arguments

data

DataFrame
Input data which includes key and endog columns and may contain exog column(s).

key

character, optional
Name of the ID column.
Defaults to the first column if not provided.

endog

character, optional
The endogenous variable, i.e. time series.
Defaults to the first non-ID column.

exog

character or list of characters, optional
An optional array of exogenous variables.
Defaults to NULL.

holiday

DataFrame, optional
Input holiday data. The structure is as follows.

  • The first column: index (ID), TIMESTAMP.

  • The second column: name, VARCHAR/NVARCHAR.

  • The third column:: lower window of holiday, INTEGER.

  • The last column:: upper window of holiday, INTEGER.

Defaults to NULL.

growth

{"linear", "logistic"}, optional
Specify a trend, which could be either linear or logistic.
Defaults to "linear".

logistic.growth.capacity

numeric, optional
Specify the carrying capacity for logistic growth.
Mandatory and valid only when the value of growth is "logistic".
Defaults to NULL.

seasonality.mode

{"additive", "multiplicative"}, optional
Mode for seasonality.
Defaults to "additive".

seasonality

character or list of characters, optional
Add seasonality to model which is a json format, include NAME, PERIOD, FOURIER_ORDER, PRIOR_SCALE, MODE.
For example: seasonality = list(' "NAME": "MONTHLY", "PERIOD":30, "FOURIER_ORDER":5 ').
Defaults to NULL.

num.changepoints

integer, optional
Number of potential changepoints.
Defaults to 25.

changepoint.range

numeric, optional
Proportion of history in which trend changepoints will be estimated.
Defaults to 0.8.

regressor

character or list of characters, optional
Specify the regressor, include NAME, PRIOR_SCALE, STANDARDIZE, and MODE, which is in json format.
For example, regressor = list(' "NAME": "X1", "PRIOR_SCALE":4, "MODE": "additive" '). Defaults to NULL.

changepoints

character or list of characters, optional
Specify a list of changepoints in the format of timestamp,
such as changepoints = list("2019-01-01 00:00:00", "2019-02-04 00:00:00"). Defaults to NULL.

yearly.seasonality

{"auto", "false", "true"}, optional
Specify 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
Specify whether or not to fit the weekly seasonality.
"auto" means automatically determined from input data.
Defaults to "auto".

daily.seasonality

{"auto", "false", "true"}, optional
Specify whether or not to fit the daily seasonality.
"auto" means automatically determined from input data.
Defaults to "auto".

seasonality.prior.scale

numeric, optional
Parameter modulating the strength of the seasonality model.
Defaults to 10.

holiday.prior.scale

numeric, optional
Parameter modulating the strength of the holiday components model.
Defaults to 10.

changepoint.prior.scale

numeric, optional
Parameter modulating the flexibility of the automatic changepoint selection.
Defaults to 0.05.

categorical.variable

character or list of characters, optional
Indicate which variables are treated as categorical. The default behavior is:

  • "VARCHAR" and "NVARCHAR": categorical.

  • "INTEGER" and "DOUBLE": continuous.

VALID only for variables of "INTEGER", "VARCHAR" and "NVARCHAR" type, omitted otherwise.
Defaults to NULL.

massive

logical, optional
Specifies whether or not to use massive mode.
For parameter setting in 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:


 > ad <- hanaml.AdditiveModelForecast(data=df,
                                      massive=TRUE,
                                      group.key='ID',
                                      changepoint.prior.scale=0.06,
                                      group.params=list('Group_1'=list('seasonality.mode'='additive')))
 

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.key

character, optional
The column of group key. The 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 group.key is not provided.

group.params

list, optional
If the massive mode is activated (massive = TRUE), input data shall be divided into different groups with different parameters applied.
An example is as follows:


> ad <- hanaml.AdditiveModelForecast(data=df,
                                       massive=TRUE,
                                       key='TIMESTAMP',
                                       endog='Y',
                                       group.key='GROUP_ID',
                                       group.params=list('Group_1'=list('seasonality.mode'='additive')))
> mres <- predict(model=ad,
                    data=pred.df,
                    key='TIMESTAMP',
                    endog='Y',
                    group.key='GROUP_ID',
                    group.params=list('Group_0'=list(decompose.seasonality=FALSE),'Group_1'=list(decompose.seasonality=TRUE)))

Valid only when massive is TRUE and defaults to NULL.

Value

Returns a "hanaml.AdditiveModelForecast" object with following values:

  • model : DataFrame
    Fitted model.

  • explainer : DataFrame
    The decomposition of trend, seasonal, holiday and exogenous variables. Only contains value when show.explainer=TRUE in the predict function.

  • error.msg : DataFrame
    Error message and only valid if massive is TRUE when create a 'hanaml.AdditiveModelForecast' instance.

Details

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

Customized Seasonalities

In Additive Model Forecast, by default

  • yearly seasonality: is fitted if the length of time series data is more than a year.

  • weekly seasonality: is fitted if the length of time series is more than a week.

  • daily seasonality: is fitted only for sub-daily time-series.

All seasonality(i.e. periodic) effects are modeled using partial Fourier sum. The number of terms in the partial sum determines how quickly the seasonality can change. For reference, the default number of Fourier terms for yearly and weekly seasonalities are 10 and 3, respectively. Increasing the Fourier order allows the seasonality to fit higher-frequency changes, but can also lead to overfitting. In most cases, the default values are appropriate.
In addition to the previously mentioned three auto-detected seasonalities, users can also add customized seasonalities(e.g. monthly, quarterly, hourly, etc.) with parameter seasonality. It accepts a string in json format with the following content:
a name, the period of the seasonality in days, the Fourier order, and optional elements prior scale and mode for the seasonality.

Relevant Parameters

  • seasonality: This parameter specifies customized seasonlaity in json format, including (keys) NAME, PERIOD, FOURIER_ORDER, PRIOR_SCALE, MODE. The former 3 are mandatory while the later 2(i.e. PRIOR_SCALE and MODE) are optioanl.

  • yearly.seasonality, weekly.seasonality, daily.seasonality: The three parameters controls whether yearly, weekly and daily seasonalities are fitted, with options "true", "false" and "auto".

  • seasonality.mode: This parameter specifies the seasonality mode, either additive or multiplicative. By default the algorithm fits additive seasonalities, meaning the effect of the seasonality is added to the trend to get the forecast. If the seasonal fluctuations grow with the trend, this is multiplicative seasonality. Any added seasonalities will by default use seasonality.model's setting, but can be overridden by specifying MODE as an element when specifiy the parameter seasonality. Note that it is pretty unlikely to have a mixture of both additive seasonality and multiplicative seasonality in a single time-series data.

  • seasonality.prior.scale: This parameter adjusts the extent to which the seasonality model will fit the data. A large value allows the seasonality to fit large fluctuations, and a small value shrinks the impact of the seasonality. By default this parameter is 10, which provides little regularization. If the seasonalities are overfitting, adjusting their prior scale will smooth them.

Examples

Input DataFrame data:


> data$Collect()
   TIMESTAMP          Y
1 2007-12-11 -0.6361264
2 2007-12-12  3.0925087
3 2007-12-13 -0.7373356
4 2007-12-14 -3.1421910

Call the function:


> amf <- hanaml.AdditiveModelForecast(data = data,
                                      yearly.seasonality = "auto",
                                      weekly.seasonality = "auto",
                                      daily.seasonality = "auto")

Output:


> amf$model$Collect()
  ROW_INDEX
1         0
MODEL_CONTENT
1 {"FLOOR":0.0,"GROWTH":"linear","SEASONALITY_MODE":"additive","beta":[[0.0]],"changepoints_t":[[0.3333333333333333,0.6666666666666666]],"delta":[[3.606905203289095e-10,2.161407465026720e-10]],"holidays_prior_scale":10.0,"k":-0.692426758115090,"m":0.04386341358443890,"sigma_obs":0.5074218980767474,"start":"2007-12-11 00:00:00.0000000","t_scale":259200.0,"y_scale":3.1421909830}\n

Additive model forecast with customized monthly seasonality:


> amf <- hanaml.AdditiveModelForecast(data=data,
                                      weekly.seasonality="false",
                                      seasonality='{"NAME": "MONTHLY", "PERIOD":30, "FOURIER_ORDER":5}')