hanaml.LinearRegression.Rd
hanaml.LinearRegression is a R wrapper for SAP HANA PAL linear regression algorithm.
hanaml.LinearRegression(
data = NULL,
key = NULL,
features = NULL,
label = NULL,
formula = NULL,
solver = NULL,
var.select = NULL,
features.must.select = NULL,
intercept = NULL,
alpha.to.enter = NULL,
alpha.to.remove = NULL,
enet.lambda = NULL,
enet.alpha = NULL,
max.iter = NULL,
tol = NULL,
pho = NULL,
stat.inf = NULL,
adjusted.r2 = NULL,
dw.test = NULL,
reset.test = NULL,
bp.test = NULL,
ks.test = NULL,
thread.ratio = NULL,
categorical.variable = NULL,
pmml.export = NULL,
resampling.method = NULL,
evaluation.metric = NULL,
fold.num = NULL,
repeat.times = NULL,
param.search.strategy = NULL,
random.search.times = NULL,
random.state = NULL,
timeout = NULL,
progress.indicator.id = NULL,
parameter.range = NULL,
parameter.values = NULL,
handle.missing = NULL,
json.export = NULL,
precompute.lms.sketch = NULL,
stable.sketch.alg = NULL,
sparse.sketch.alg = NULL,
resource = NULL,
max.resource = NULL,
min.resource.rate = NULL,
reduction.rate = NULL,
aggressive.elimination = NULL,
ps.verbose = NULL
)
DataFrame
DataFrame containting the data.
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.
Defaults to the last column of data if not provided.
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.
c("QR", "SVD", "CD", "Cholesky", "ADMM"), optional
Algorithms to use to solve the least square problem.
"CD" and "ADMM" are supported only when var_select is "all".
"QR": QR decomposition(numerically stable, but fails when A is rank-deficient).
"SVD": singular value decomposition(numerically stable and can handle rank deficiency but computationally expensive).
"CD": cyclical coordinate descent methodto solve elastic net regularized multiple linear regression.
"Cholesky": Cholesky decomposition(fast but numerically unstable).
"ADMM": Alternating direction method of multipliers (ADMM) to solve elastic net regularized multiple linear regression. This method is faster than the cyclical coordinate descent method in many cases and recommended.
Defaults to "QR".
c("all", "forward", "backward", "stepwise"), optional
Method to perform variable selection.
"all": all variables are included.
"forward": forward selection.
"backward": backward selection.
"stepwise": stepwise selection.
"forward", "backward" and "stepwise" are supported only when solver is "QR", "SVD" or "Cholesky".
Defaults to "all".
character or list/vector of characters, optional
Specifies the column names of data that needs to be included in the final
training model when executing variable selection.
Only valid when var.select is not "all".
Note: This parameter is a hint.
There are exceptional cases that a specified mandatory feature is excluded in the final model.
For instance, some mandatory features can be represented as a linear combination
of other features, among which some are also mandatory features.
No default value.
logical, optional
If TRUE, include the intercept in the model.
Defaults to TRUE.
double, optional
P-value for forward selection.
When var.select is 'forward', default value is 0.05; when var.select is "stepwise", default value is 0.15.
double, optional
P-value for backward selection.
When var.select is 'backward', default value is 0.1; when var.select is "stepwise", default value is 0.15.
double, optional
Penalized weight. Value should be greater than or equal to 0.
Valid only when solver is "CD" or "ADMM".
double, optional
Elastic net mixing parameter.
Ranges from 0 (Ridge penalty) to 1 (LASSO penalty) inclusively.
Valid only when solver is "CD" or "ADMM".
Defaults to 1.0.
integer, optional
Maximum number of passes over training data.
If convergence is not reached after the specified number of
iterations, an error will be generated.
Valid only when solver is "CD" or "ADMM".
Defaults to 1e5.
double, optional
Convergence threshold for coordinate descent.
Valid only when solver is "CD".
Defaults to 1.0e-7.
double, optional
Step size for ADMM. Generally, it should be greater than 1.
Valid only when solver is "ADMM".
Defaults to 1.8.
logical, optional
If TRUE, output t-value and Pr(>|t|) of coefficients.
Defaults to FALSE.
logical, optional
If TRUE, include the adjusted R^2 value in statistics.
Defaults to FALSE.
logical, optional
If TRUE, conduct Durbin-Watson test under null hypothesis that
errors do not follow a first order autoregressive process.
Not available if elastic net regularization is enabled or
intercept is ignored.
Defaults to FALSE.
integer, optional
Specifies the order of Ramsey RESET test.
Ramsey RESET test with power of variables ranging from 2
to this value (greater than 1) will be conducted.
Value 1 means RESET test will not be conducted.
Not available if elastic net regularization is enabled or
intercept is ignored.
Defaults to 1.
logical, optional
If TRUE, conduct Breusch-Pagan test under null hypothesis that
homoscedasticity is satisfied.
Not available if elastic net regularization is enabled or
intercept is ignored.
Defaults to FALSE.
logical, optional
If TRUE, conduct Kolmogorov-Smirnov normality test under
null hypothesis that errors follow a normal distribution.
Not available if elastic net regularization is enabled or
intercept is ignored.
Defaults to FALSE.
double, optional
Controls the proportion of available threads that can be used by this
function.
The value range is from 0 to 1, where 0 indicates a single thread,
and 1 indicates all available threads.
Values between 0 and 1 will use up to
that percentage of available threads.Values outside this
range are ignored.
Defaults to 0.
character or list/vector of characters, optional
Indicates features should be treated as categorical variable.
The default behavior is dependent on what input is given:
"VARCHAR" and "NVARCHAR": categorical
"INTEGER" and "DOUBLE": continuous.
VALID only for variables of "INTEGER" type, omitted otherwise.
No default value.
c("no", "multi-row"), optional
Controls whether to output a PMML representation of the model,
and how to format the PMML.
"no":
Does not export multiple linear regression model in PMML.
"multi-row":
Exports a PMML model, exports multiple linear regression model in PMML.
The maximum length of each row is 5000 characters.
Currently either PMML or JSON format model can be exported. JSON format is preferred if both formats are to be exported. Default to "no".
character, optional
Specifies the resampling method for model evaluation or parameter selection
from the list below:
"cv", "cv_sha", "cv_hyperband", "bootstrap", "bootstrap_sha", "bootstrap_hyperband".
If no value is specified, neither model evaluation
nor parameter selection is activated.
character, optional
Specifies the evaluation metric for model evaluation or parameter selection.
Currently the only valid option(also the default value) is "rmse".
integer, optional
Specifies the fold number for cross-validation(cv).
Mandatory and valid only when resampling.method
is one of the following: "cv", "cv_sha",
"cv_hyperband".
numeric, optional
Specifies the number of repeat times for resampling.
Defaults to 1.
c("grid", "random"), optional
Specifies the method to activate parameter selection.
If not specified, model parameter selection shall not be triggered.
Defaults to "random" and cannot be changed if resampling.method
is set as "cv_hyperband" or "bootstrap_hyperband"; otherwise no
default value.
integer, optional
Specifies the number of times to randomly select candidate parameters for selection.
Mandatory and valid only when param.search.strategy
is set as "random", or when
resampling.method
is set as "cv_hyperband" or "bootstrap_hyperband".
numeric, optional
Specifies the seed for random generation.
Use system time when 0 is specified.
integer, optional
Specifies maximum running time for model evaluation or parameter selection in seconds.
No timeout when 0 is specified.
character, optional
Sets an ID of progress indicator for model evaluation or parameter selection.
No progress indicator is active if no value is provided.
list, optional
Specifies range of the following parameters for parameter selection:enet.lambda, enet.alpha
.
Parameter range should be specified by 3 numbers in the form of c(start, step, end).
Examples:
parameter.range <- list(enet.lambda = c(0.01, 0.01, 0.1)), which means taking
enet.lambda
values from 0.01 to 0.1 with 0.01 being the step size, i.e.
0.01, 0.02, 0.03, ..., 0.09, 0.1.
If param.search.strategy
is "random", then the middle term,
i.e. step has no effect and thus can be omitted.
list, optional
Specifies values of the following parameters for parameter selection:enet.lambda, enet.alpha
.
Example: parameter.values <- list(enet.lambda = c(0.001, 0.003, 0.007, 0.01))
logical, optional
Specifies whether or not to handle missing/null values in data
.
Defaults to TRUE.
logical, optional
FALSE:
Does not export multiple linear regression model in JSON.
TRUE:
Exports multiple linear regression model in JSON.
Currently either PMML or JSON format model can be exported.
JSON format is preferred if both formats are to be exported.
Default to FALSE.
logical, optional
FALSE: Do not perform LMS sketch.
TRUE: Performs LMS sketch.
Valid only when resampling.method
is set,
and data
has more rows than columns.
Defaults to TRUE.
logical, optional
When computing LMS sketch, there are two algorithms to choose: one is more numerical stable
than the other but slower. This parameter specifies whether or not to choose the stable algorithm.
FALSE: Do not use the stable algorithm.
TRUE: Uses the stable algorithm.
Valid only when precompute.lms.sketch
is valid and set as TRUE.
Defaults to TRUE.
logical, optional
Specifies whether or not to invoke the LMS sketch algorithm to with sparse data.
FALSE: Do not use sparse LMS sketch algorithm.
TRUE: Uses sparse LMS sketch algorithm.
Only valid when precompute.lms.sketch
is valid and set as TRUE.
Warning: Please Use this option with caution.
If the provided data are not sparse, turning on this option will cause LMS sketch to be
extremely slow!
integer, optional
Specifies the maximum allowed resource budget for single hyper-parameter candidate,
whose value must be greater than 0.
Mandatory and valid only wen resource
is set.
numeric, optional
Specifies the rate between minimum allowed resource and maximum allowed resource.
Valid range is [0, 1).
Valid only when resource
is specified.
Defaults to 0.
numeric, optional
Specifies the reduction rate of available size of hyper-parameter candidates.
For each round, the available parameter candidate size will be divided by value of this parameter.
Thus valid value for this parameter must be greater than 1.0
Valid only when resource
is set.
Defaults to 3.0.
logical, optional
Specifies whether to perform aggressive elimination behavior for successive-halving algorithm or not.
When set to TRUE, it will eliminate more parameter candidates than
expected(defined via reduction_rate
).
This can enhance the run-time performance but could result in sub-optimal hyper-parameter candidate.
Valid only when resampling_method
is "cv_sha" or "bootstrap_sha".
Defaults to FALSE.
logical, optional
Specifies whether to output optimal hyper-parameter and all evaluation statistics of related
hyper-parameter candidates in attribute statistics or not.
Defaults to TRUE.
character, optional
Specifies the resource type used in successive-halving and hyperband algorithm for parameter selection.
Currently the only valid option is "max_iter".
Mandatory and valid only when resampling_method
is set as one of the following: "cv_sha",
"bootstrap_sha", "cv_hyperband" or "bootstrap_hyperband".
Returns an R6 object of class "LinearRegression" with the following attributes and methods:
Attributes
coefficients : DataFrame
Fitted regression coefficients.
fitted : DataFrame
Predicted dependent variable values for training data.
Set to NULL if the training data has no row IDs.
statistics : DataFrame
Regression-related statistics, such as mean squared error.
optim.param : DataFrame
Optimal parameters selected. Available only when parameter selection
is activated.
pmml : DataFrame
PMML model. (deprecate as JSON format is also supported in the model).
Please use semistructured.result shown below to get the model.
semistructured.result : DataFrame
The linear regression model in PMML or JSON format.
Methods
CreateModelState(model=NULL, algorithm=NULL, func=NULL, state.description="ModelState", force=FALSE)
Usage:
> mlr <- hanaml.LinearRegression(data=df)
> mlr$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:
> mlr <- hanaml.LinearRegression(data=df)
> mlr$CreateModelState()
After using the model state for real-time scoring, we can delete the state by calling:
> mlr$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.
Linear regression is an approach to model the linear relationship between a variable, usually referred to as dependent variable, and one or more variables, usually referred to as independent variables, denoted as predictor vector.
Input DataFrame data:
> data$Collect()
ID Y X1 X2 X3
1 0 -6.879 0.00 A 1
2 1 -3.449 0.50 A 1
3 2 6.635 0.54 B 1
4 3 11.844 1.04 B 1
5 4 2.786 1.50 A 1
6 5 2.389 0.04 B 2
7 6 -0.011 2.00 A 2
8 7 8.839 2.04 B 2
9 8 4.689 1.54 B 1
10 9 -5.507 1.00 A 2
Model traning and a "LinearRegression" object lr is returned:
>lr <- LinearRegression(data = data, key = "ID",
label = "Y", thread.ratio = 0.5,
categorical.variable = list("X3"))
Output:
> lr$coefficients$Select(c("VARIABLE_NAME",
"COEFFICIENT_VALUE"))
VARIABLE_NAME COEFFICIENT_VALUE
1 __PAL_INTERCEPT__ -5.7045
2 X1 3.0925
3 X2__PAL_DELIMIT__A 0.0000
4 X2__PAL_DELIMIT__B 9.3675
5 X3__PAL_DELIMIT__1 0.0000
6 X3__PAL_DELIMIT__2 -2.6895