hanaml.UnifiedRegression.Rd
hanaml.UnifiedRegression is an R wrapper for SAP HANA PAL Unified Regression.
hanaml.UnifiedRegression(
data = NULL,
func = NULL,
key = NULL,
features = NULL,
label = NULL,
purpose = NULL,
formula = NULL,
partition.method = NULL,
partition.random.state = NULL,
training.percent = NULL,
output.partition.result = NULL,
background.size = NULL,
background.random.state = NULL,
categorical.variable = NULL,
impute = FALSE,
strategy = NULL,
strategy.by.col = NULL,
als.factors = NULL,
als.lambda = NULL,
als.maxit = NULL,
als.randomstate = NULL,
als.exit.threshold = NULL,
als.exit.interval = NULL,
als.linsolver = NULL,
als.cg.maxit = NULL,
als.centering = NULL,
als.scaling = NULL,
c = NULL,
massive = FALSE,
group.key = NULL,
group.params = NULL,
output.coefcov = NULL,
output.leaf.values = NULL,
...
)
DataFrame
DataFrame containting the data.
character
The functionality for unified regression.
Valid values are as follows:
"DecisionTree", "RandomDecisionTrees", "HGBT", "LinearRegression",
"SVM", "MLP", "PolynomialRegression", "LogarithmicRegression",
"ExponentialRegression", "GeometricRegression",
"GLM".
character, optional
Name of the ID column.
If not provided, the data is assumed to have no ID column.
No default value.
character of list of characters, optional
Name of feature columns.
If not provided, it defaults all non-key, non-label columns of data.
character, optional
Name of the column which specifies the dependent variable.
If not specified, defaults to the last non-purpose column.
character, optional
Name of the column which specified user-defined data partition.
Mandatory if partition.method is "predefined".
formula type, optional
Formula to be used for model generation.
format = label~<feature_list>
e.g.: formula=CATEGORY~V1+V2+V3
You can either give the formula,
or a feature and label combination, but do not provide both.
Defaults to NULL.
character, optional
Specified the method for partitioning the training data.
Valid options include: "no", "predefined", "random".
Defaults to "no" if not specified (i.e. no data partition).
character, optional
Specifies the random seed for stratified partition.
Valid only when partition.method
is set to "random".
Defaults to 0(system time).
numeric, optional
Specifies the percentage of data used for training.
Valid only when partition.method
is set to "random".
Defaults to 0.8.
logical, optional
Specifies whether or not to output the partition result of the training data.
Defaults to FALSE.
integer, optional
Specifies the row size of background data(for SHAP value computation).
It should not be larger than the row size of train data.
Valid only when func
takes one of the following values: "ExponentialRegression",
"GLM", "LinearRegression", "MLP" and "SVM".
Defaults to 0(i.e. no background data, thus no local model interpretability).
integer, optional
Specified the seed for random number generator in the background data sampling:
0: Use current system time as seed.
others : Use the specified value as seed.
Valid only when func
takes one of the following values: "ExponentialRegression",
"GLM", "LinearRegression", "MLP" and "SVM".
Defaults to 0.
logical, optional
Specifies whether or not to handle missing values in the data for scoring.
Defaults to FALSE.
character, optional
Specifies the overall
imputation strategy for the input scoring data.
"non"
: No imputation for all
columns.
"most_frequent.mean"
: Replacing missing values in any categorical column by its most frequently observed value, and
missing values in any numerical column by its mean.
'most_frequent.median' : Replacing missing values in any categorical column by its most frequently observed value, and missing values in any numerical column by its median.
"most_frequent.median"
: Replacing missing values in any categorical column by its most frequently observed value, and
missing values in all numerical columns by zeros.
"most_frequent.zero"
: Replacing missing values in any categorical column by
its most frequently observed value, and filling the missing values in all numerical columns via a
matrix completion technique called alternating least squares.
"most_frequent.als"
: For numerical columns, fills each missing value by the value imputed by a
matrix completion model trained using alternating least squares method;
for categorical columns, fills all missing values with the most frequent value.
'delete'
: Delete all
rows with missing values.
Valid only when impute
is TRUE.
Defaults to 'most_frequent.mean'.
list, optional
Specifies the imputation strategy for a set of columns, which
overrides the overall strategy for data imputation.
Elements of this list must be named. The names must be column names,
while each value should either be the imputation strategy applied to that column,
or the replacement for all missing values within that column.
Valid column imputation strategies are listed as follows:
"mean", "median", "als", "non", "delete", "most_frequent".
The first five strategies are applicable to numerical columns, while the final three
strategies are applicable to categorical columns.
An illustrative example:
stragegy.by.col = list(V1 = 0, V5 = "median"),
which mean for column V1, all missing values shall be replaced by constant 0;
while for column V5, all missing values shall be by replaced by the median of all
available values in that column.
No default value.
integer, optional
Length of factor vectors in the ALS model.
It should be less than the number of numerical columns,
so that the imputation results would be meaningful.
Defaults to 3.
double, optional
L2 regularization applied to the factors in the ALS model.
Should be non-negative.
Defaults to 0.01.
integer, optional
Specifies the maximum number of iterations for cg algorithm.
Invoked only when the 'cg' is the chosen linear system solver for ALS.
Defaults to 3.
integer, optional
Specifies the seed of the random number generator used in the training of ALS model.
0 means to use the current time as the seed and Others number is to use the specified value as the seed.
Defaults to 0.
double, optional
Specify a value for stopping the training of ALS model.
If the improvement of the cost function of the ALS model
is less than this value between consecutive checks, then
the training process will exit.
0 means there is no checking of the objective value when
running the algorithms, and it stops till the maximum number of
iterations has been reached.
Defaults to 0.
integer, optional
Specify the number of iterations between consecutive checking of
cost functions for the ALS model, so that one can see if the
pre-specified exit.threshold
is reached.
Defaults to 5.
c('cholesky', 'cg'), optional
Linear system solver for the ALS model.
'cholesky' is usually much faster
'cg' is recommended when als.factors
is large.
Defaults to 'cholesky'.
logical, optional
Whether to center the data by column before training the ALS model.
Defaults to TRUE.
logical, optional
Whether to scale the data by column before training the ALS model.
Defaults to TRUE.
double, optional
Trade-off between training error and margin for SVM Regression.
Valid only when func
is "SVM".
Must be positive.
Defaults to 100.
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:
> mur <- hanaml.UnifiedRegression(func='hgbt',
massive=TRUE,
thread.ratio=0.5,
data=df.fit,
group.key="GROUP_ID",
key="ID",
features=list("X1", "X2", "Y"),
label='X3',
group.params=list("Group_1"=list(partition.method = 'random')))
In this example, as 'partition.method' is set in group.params for Group_1,
parameter setting of 'thread.ratio' is not applicable to Group_1.
Defaults to FALSE.
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.
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:
> mur <- hanaml.UnifiedRegression(func='hgbt',
massive=TRUE,
thread.ratio=0.5,
data=df.fit,
group.key="GROUP_ID",
key="ID",
features=list("X1", "X2", "Y"),
label='X3',
group.params=list("Group_1"=list(partition.method = 'random'))
> res <- predict(mur,
data=df.predict,
group.key="GROUP_ID",
key="ID",
group.params= list("Group_1"=list(impute=TRUE))
Valid only when massive is TRUE and defaults to NULL.
logical, optional
Specifies whether or not to output coefficient covariance information
for Linear Regression.
Valid only if func
is specified as "LinearRegression" and
json.export
is specified as TRUE.
Defaults to FALSE.
Note: To enable output of confidence/prediction interval for Linear Regression model
in UnifiedRegression during predicting/scoring phase, we need to set output.coefcov
as 1.
logical, optional
Specifies whether or not save the target target values in
each leaf node in the training phase for Random Decision Trees model(otherwise only mean of the target values is saved in the model).
Setting the value of this parameter as True to enable the output of prediction interval for Random Decision Trees model in UnifiedRegression
during predicting/scoring phase.
Valid only for fitting Random Decision Trees model(i.e. setting func
as 'RandomDecisionTrees') when model.format
is "json" or compression
is TRUE.
Defaults to False.
Specifies other parameters for training a regression model with the functionality
specified in func.
Please see the documentation of corresponding functionalities for more detail.hanaml.DecisionTreeRegressor,
hanaml.RDTRegressor,
hanaml.MLPRegressor,
hanaml.HGBTRegressor,
hanaml.SVR,
hanaml.ExponentialRegression,
hanaml.LogarithmicRegression,
hanaml.PolynomialRegression,
hanaml.GeometricRegression,
hanaml.LinearRegression,
hanaml.GLM
However, some parameters will be disabled. The disable parameters are listed as follows:
DecisionTreeRegressor: output.rules
.
RDTRegressor: calculate.oob
.
HGBTRegressor: calculate.importance
.
GLM: output.fitted
.
ExponentialRegression: pmml.export
.
GeometricRegression: pmml.export
.
PolynomialRegression: pmml.export
.
LogarithmicRegression: pmml.export
.
LinearRegression: pmml.export
.
Note that for LinearRegression, the meaning of Parameter json.export has changed, where FALSE means
to export multiple linear regression model in PMML and TRUE remains to export model in JSON.
Returns an R6 object of class "UnifiedRegression" with the following attributes and methods:
Attributes
modelDataFrame
ROW_INDEX
- model row index
PART_INDEX
- data partition index
MODEL_CONTENT
- model content
importanceDataFrame
VARIABLE_NAME
- Independent variable name
IMPORTANCE
- Variable importance
optimal.paramDataFrame
PARM_NAME
- parameter name
INT_VALUE
- integer value
DOUBLE_VALUE
- double value
STRING_VALUE
- character value
statisticsDataFrame
STAT_NAME
- Statistics name
STAT_VALUE
- Statistics value
confusion.matrixDataFrame
ACTUAL_CLASS
- The actual class name
PREDICTED_CLASS
- The predicted class name
COUNT
- Number of records
metricsDataFrame
NAME
- Metric name
X
- X value
Y
- Y value
Methods
CreateModelState(model=NULL, algorithm=NULL, func=NULL, state.description="ModelState", force=FALSE)
Usage:
> umlr <- hanaml.UnifiedRegression(data=df, func="LinearRegression")
> umlr$CreateModelState()
Arguments:
model: DataFrame
DataFrame containing the model for parsing.
Defaults to self$model
.
algorithm: character
Specifies the PAL algorithm associated with model
.
Defaults to self$pal.algorithm
.
func: character
Specifies the functionality for Unified Classification/Regression.
Valid only for object instance of R6Class "UnifiedClassification" or "UnifiedRegression".
Defaults to self$func
.
state.description: character
A summary string for the generated model state.
Defaults to "ModelState".
force: logic
Specifies whether or not the replace existing state for model
.
Defaults to FALSE.
After calling this method, an attribute state
that contains the parsed info for model
shall be assigned
to the corresponding R6 object.
DeleteModelState(state=NULL)
Usage:
Assuming we have trained a hanaml
model and created its model state, like the following:
> umlr <- hanaml.UnifiedRegression(data=df, func="LinearRegression")
> umlr$CreateModelState()
After using the model state for real-time scoring, we can delete the state by calling:
> umlr$DelateModelState()
Arguments:
state: DataFrame
DataFrame containing the state info.
Defaults to self$state
.
After calling this method, the specified model state shall be cleaned up and associated memory be released.
The training data:
> data.fit
ID X1 X2 X3 Y
1 0 0.00 A 1 -6.879
2 1 0.50 A 1 -3.449
3 2 0.54 B 1 6.635
4 3 1.04 B 1 11.844
5 4 1.50 A 1 2.786
6 5 0.04 B 2 2.389
7 6 2.00 A 2 -0.011
8 7 2.04 B 2 8.839
9 8 1.54 B 1 4.689
10 9 1.00 A 2 -5.507
Create a UnifiedRegression model for linear regression:
> umlr <- hanaml.UnifiedRegression(data = data.fit,
key = "ID",
label = "Y",
solver = "qr",
adjusted.r2 = FALSE,
func="LinearRegression",
thread.ratio=0.5,
partition.method="random",
training.percent=0.7,
partition.random.state=2,
output.partition.result=TRUE,
output.coefcov=TRUE)
Check the resulting statistics:
> umlr$statistics
STAT_NAME STAT_VALUE
1 TEST_EVAR 0.871459247598903
2 TEST_MAE 2.0088082000000003
3 TEST_MAPE 12.260003987804756
4 TEST_MAX_ERROR 5.329849599999999
5 TEST_MSE 9.551661310681718
6 TEST_R2 0.7774293644548433
7 TEST_RMSE 3.09057621013974
8 TEST_WMAPE 0.7188006440839695
Data for model scoring:
> df.score
ID X1 X2 X3 Y
1 0 1.690 B 1 1.2
2 1 0.054 B 2 2.1
3 2 980.123 A 2 2.4
4 3 1.000 A 1 1.8
5 4 0.563 A 1 1.0
Apply the obtained linear regression model to the scoring data:
> score.res <- score(umlr, data = df.score, key = "ID", label = "Y")
Check the statistics on scoring data:
> score.res[[2]]$Collect()
STAT_NAME STAT_VALUE
1 EVAR -6284768.906191169
2 MAE 666.5116459919999
3 MAPE 278.9837795885635
4 MAX_ERROR 3315.9714402299996
5 MSE 2199151.795823181
6 R2 -7854112.55651136
7 RMSE 1482.9537402842952
8 WMAPE 392.0656741129411
Prediction of target values as well as intervals:
> df.pred
ID X1 X2 X3
1 0 1.690 B 1
2 1 0.054 B 2
3 2 980.123 A 2
4 3 1.000 A 1
5 4 0.563 A 1
> pred.res <- predict(umlr, data = df.pred, key = "ID",
features = list("X1", "X2", "X3"),
significance.level = 0.05,#specify the significance level
interval.type = "prediction")# specify the interval type