hana_ml.algorithms.apl package¶

Overview¶

The APL (Automated Predictive Library) package provides automated machine learning algorithms for SAP HANA. This package includes both modern Gradient Boosting algorithms and legacy algorithms.

Python API to APL SQL API Mapping¶

The following table shows the relationship between hana-ml Python classes and their corresponding APL SQL API model types:

Class to Model Type Mapping¶
Python API Class	APL SQL Model Type	Status
`GradientBoostingBinaryClassifier`	binary classification	Recommended
`GradientBoostingClassifier`	multiclass	Recommended
`GradientBoostingRegressor`	regression	Recommended
`AutoTimeSeries`	timeseries	Recommended
`AutoUnsupervisedClustering`	clustering	Recommended
`AutoSupervisedClustering`	clustering	Recommended
`DriftDetector`	statbuilder / variable-encoder*	Recommended
`AutoClassifier`	regression/classification	Legacy
`AutoRegressor`	regression/classification	Legacy

* Uses variable-encoder when there is a target variable, statbuilder otherwise.

For detailed information about APL model types, see Model Types in the SAP HANA APL Developer Guide.

Note

Use Recommended algorithms for new projects. Legacy algorithms are still supported but have been superseded by newer alternatives.

For more information about the differences between Gradient Boosting models and Legacy models, see Gradient Boosting Versus Legacy Models.

Available Modules¶

APL Package consists of the following sections:

hana_ml.algorithms.apl.gradient_boosting_classification
hana_ml.algorithms.apl.gradient_boosting_regression
hana_ml.algorithms.apl.time_series
hana_ml.algorithms.apl.classification
hana_ml.algorithms.apl.regression
hana_ml.algorithms.apl.clustering
hana_ml.algorithms.apl.drift_detector

hana_ml.algorithms.apl.gradient_boosting_classification¶

This module provides the SAP HANA APL gradient boosting classification algorithm.

The following classes are available:

GradientBoostingBinaryClassifier

GradientBoostingClassifier

class hana_ml.algorithms.apl.gradient_boosting_classification.GradientBoostingClassifier(conn_context=None, early_stopping_patience=None, eval_metric=None, learning_rate=None, max_depth=None, max_iterations=None, number_of_jobs=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, interactions=None, interactions_max_kept=None, variable_auto_selection=None, variable_selection_max_nb_of_final_variables=None, variable_selection_max_iterations=None, variable_selection_percentage_of_contribution_kept_by_step=None, variable_selection_quality_bar=None, cutting_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: _GradientBoostingClassifierBase

SAP HANA APL Gradient Boosting Multiclass Classifier algorithm.

Parameters

conn_contextConnectionContext, optional

The connection object to an SAP HANA database. This parameter is not needed anymore. It will be set automatically when a dataset is used in fit() or predict().

early_stopping_patienceint, optional

If the performance does not improve after early_stopping_patience iterations, training stops before reaching max_iterations. Default is 10.

eval_metricstr, optional

The metric used to evaluate model performance on the validation dataset along the boosting iterations. The possible values are 'MultiClassClassificationError' and 'MultiClassLogLoss'. Default is 'MultiClassLogLoss'.

learning_ratefloat, optional

The shrinkage factor applied to each tree's contribution during boosting. A smaller value reduces the step size at each iteration, which typically requires more iterations to converge but can improve the robustness of the model. Default is 0.1.

max_depthint, optional

The maximum depth of the decision trees added as a base learner at each boosting iteration. Default is 4.

max_iterationsint, optional

The maximum number of boosting iterations to fit the model. Default is 1000.

number_of_jobsint, optional

Deprecated.

variable_storagesdict, optional

Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.

variable_value_typesdict, optional

Specifies the variable value type (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.

variable_missing_stringsdict, optional

Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.

extra_applyout_settingsdict, optional

Determines the output of the predict() method. These settings can also be passed directly as the prediction_type argument of predict(). The possible values are:

By default (None): the default output columns are:
- <KEY> — the key column if provided in the dataset.
- TRUE_LABEL — the class label if provided in the dataset.
- PREDICTED — the predicted label.
- PROBABILITY — the probability of the prediction.
{'APL/ApplyExtraMode': 'AllProbabilities'} — the probabilities for each class:
- <KEY> — the key column if provided.
- TRUE_LABEL — the class label if given.
- PREDICTED — the predicted label.
- PROBA_<label_value1> — the probability for class <label_value1>.
- ...
- PROBA_<label_valueN> — the probability for class <label_valueN>.
{'APL/ApplyExtraMode': 'Individual Contributions'} — SHAP-based feature contribution for each sample:
- <KEY> — the key column if provided.
- TRUE_LABEL — the class label if provided.
- PREDICTED — the predicted label.
- gb_contrib_<VAR1> — the contribution of variable VAR1 to the score.
- ...
- gb_contrib_<VARN> — the contribution of variable VARN to the score.
- gb_contrib_constant_bias — the constant bias contribution.

max_tasksint, optional

Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.

segment_column_namestr, optional

Name of the column containing the segment key, enabling one-model-per-segment training.

interactionsbool, optional

If True, activates computation of SHAP interaction values between variables. Default is False.

interactions_max_keptint, optional

Maximum number of interactions to keep per variable. Default is 5.

variable_auto_selectionbool, optional

If True, automatically reduces the number of variables while maintaining model quality. Default is False.

variable_selection_max_nb_of_final_variablesint, optional

Maximum number of variables to retain in the final model. -1 keeps all variables. Default is -1.

variable_selection_max_iterationsint, optional

Maximum number of variable selection iterations. Default is 2.

variable_selection_percentage_of_contribution_kept_by_stepfloat, optional

Fraction of information to retain at each selection step. Default is 0.90.

variable_selection_quality_barfloat, optional

Maximum accepted absolute Balanced Classification Rate difference between the initial model (trained with all input variables) and the model resulting from the variable selection process. A higher value results in fewer retained variables. Default is 0.01.

cutting_strategystr, optional

Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.

other_train_apl_aliasesdict, optional

Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

labelstr: The target column name. Set when fit() is called.
model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`build_report`([max_local_explanations])	Build and store the model HTML report.
`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, label, weight, ...])	Fit the model.
`generate_html_report`(filename)	Save model report as a html file.
`generate_notebook_iframe_report`()	Render model report as a notebook iframe.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_best_iteration`()	Return the iteration that provided the best performance on the validation dataset.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_evalmetrics`()	Return the values of the evaluation metric at each training iteration.
`get_feature_importances`()	Return the feature importances.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_metrics_per_class`()	Return the performance metrics for each class.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the last trained model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data[, prediction_type])	Make predictions with the fitted model.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`score`(data)	Compute the accuracy score on the provided test dataset.
`set_framework_version`(framework_version)	Switch v1/v2 version of report.
`set_metric_samplings`([roc_sampling, ...])	Set metric samplings to report builder.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.
`set_shapley_explainer_of_predict_phase`(...)	Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.
`set_shapley_explainer_of_score_phase`(...[, ...])	Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. The key is particularly useful to join the predictions output to the input dataset.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingClassifier
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn,
                        'SELECT "id", "class", "capital-gain", '
                        '"native-country" FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = GradientBoostingClassifier()
>>> model.fit(hana_df, label='native-country', key='id')

Getting variable interactions

>>> model.set_params(interactions=True, interactions_max_kept=3)
>>> model.fit(data=hana_df, key='id', label='native-country')
>>> # Checks interaction info in INDICATORS table
>>> output = model.get_indicators().filter("KEY LIKE 'Interaction%'").collect()

Debriefing

>>> # Global performance metrics of the model
>>> model.get_performance_metrics()
{'BalancedErrorRate': 0.9761904761904762, 'BalancedClassificationRate': 0.023809523809523808, ...}

>>> # Performance metrics of the model for each class
>>> model.get_metrics_per_class()
{'Precision': {'Cambodia': 0.0, 'Canada': 0.0, 'China': 0.0, 'Columbia': 0.0, ...}, ...}

>>> model.get_feature_importances()
{'Gain': OrderedDict([('class', 0.7713800668716431), ('capital-gain', 0.22861991822719574), ...]), ...}

Generating the model report

>>> from hana_ml.visualizers.unified_report import UnifiedReport
>>> UnifiedReport(model).build().display()

Making predictions

>>> # Default output
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().head(3) # returns the output as a pandas DataFrame
    id     TRUE_LABEL      PREDICTED  PROBABILITY
0   30  United-States  United-States      0.89051
1   63  United-States  United-States      0.89051
2   66  United-States  United-States      0.89051

>>> # All probabilities
>>> model.set_params(extra_applyout_settings={'APL/ApplyExtraMode': 'AllProbabilities'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().head(3) # returns the output as a pandas DataFrame
          id     TRUE_LABEL      PREDICTED      PROBA_?     PROBA_Cambodia  ...
35194  19272  United-States  United-States     0.016803           0.000595  ...
20186  39624  United-States  United-States     0.017564           0.001063  ...
43892  38759  United-States  United-States     0.019812           0.000353  ...

>>> # Individual contributions
>>> model.set_params(extra_applyout_settings={'APL/ApplyExtraMode': 'Individual Contributions'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().head(3) # returns the output as a pandas DataFrame
   id     TRUE_LABEL      PREDICTED  gb_contrib_class  gb_contrib_capital-gain  ...
0  30  United-States  United-States         -0.025366                -0.014416  ...
1  63  United-States  United-States         -0.025366                -0.014416  ...
2  66  United-States  United-States         -0.025366                -0.014416  ...

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> from hana_ml.model_storage import ModelStorage
>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Reloading the model for new predictions

>>> model2 = model_storage.load_model(name='My model name')
>>> out2 = model2.predict(data=hana_df)

Exporting the model in JSON format

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: The names and values of the attributes to change.

Returns

self: The updated model instance.

fit(data, key=None, features=None, label=None, weight=None, build_report=False)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. This is not recommended. See notes below.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all non-ID and non-label columns will be used.
labelstr, optional: The name of the label column. Default is the last column.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.
build_reportbool, optional: Whether to build the model HTML report after training. Default is False.

Returns

self: The fitted model instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. That is particularly inconvenient to join the predictions output to the input dataset.

score(data)¶

Compute the accuracy score on the provided test dataset.

Parameters

dataDataFrame: The test dataset used to compute the score. The labels must be provided in the dataset.

Returns

float or pandas.DataFrame: If no segment column is given, the accuracy score. If a segment column is given, a pandas.DataFrame with the accuracy score for each segment.

get_metrics_per_class()¶

Return the performance metrics for each class.

Returns

dict or pandas.DataFrame: If no segment column is given, a nested dictionary {'metric_name': {'class_name': value}}. If a segment column is given, a pandas.DataFrame.

Raises

FitIncompleteError: If fit() has not been called yet.

Examples

>>> data = DataFrame(conn, 'SELECT * FROM IRIS_MULTICLASSES')
>>> model = GradientBoostingClassifier(conn)
>>> model.fit(data=data, key='ID', label='LABEL')
>>> model.get_metrics_per_class()
{
'Precision': {
    'setosa': 1.0,
    'versicolor': 1.0,
    'virginica': 0.9743589743589743
},
'Recall': {
    'setosa': 1.0,
    'versicolor': 0.9714285714285714,
    'virginica': 1.0
},
'F1Score': {
    'setosa': 1.0,
    'versicolor': 0.9855072463768115,
    'virginica': 0.9870129870129869
}

build_report(max_local_explanations=100)¶

Build and store the model HTML report.

This method only prepares and stores the report data internally. Call generate_html_report() or generate_notebook_iframe_report() afterwards to render or export it.

Parameters

max_local_explanationsint, optional: Maximum number of local explanations displayed in the report. Default is 100. Only effective when predict() was called before build_report() with prediction_type='Explanations'. Has no effect otherwise.

set_metric_samplings(roc_sampling=None, other_samplings: dict = None)¶

Set metric samplings to report builder.

Parameters

roc_samplingSampling, optional

ROC sampling.

other_samplingsdict, optional

Key is column name of metric table.

CUMGAINS

RANDOM_CUMGAINS

PERF_CUMGAINS

LIFT

RANDOM_LIFT

PERF_LIFT

CUMLIFT

RANDOM_CUMLIFT

PERF_CUMLIFT

Value is sampling.

Examples

Creating the metric samplings:

>>> roc_sampling = Sampling(method='every_nth', interval=2)

>>> other_samplings = dict(CUMGAINS=Sampling(method='every_nth', interval=2),
                      LIFT=Sampling(method='every_nth', interval=2),
                      CUMLIFT=Sampling(method='every_nth', interval=2))
>>> model.set_metric_samplings(roc_sampling, other_samplings)

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

generate_html_report(filename)¶

Save model report as a html file.

Parameters

filenamestr: Html file name.

generate_notebook_iframe_report()¶: Render model report as a notebook iframe.

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_best_iteration()¶

Return the iteration that provided the best performance on the validation dataset.

Returns

int or pandas.DataFrame: If no segment column is configured, the best iteration as an integer. If a segment column is configured, a pandas.DataFrame with the best iteration for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_evalmetrics()¶

Return the values of the evaluation metric at each training iteration.

These values are computed on the validation dataset.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping metric name to a list of values, one per iteration: {'<MetricName>': [<value>, ...]}. If a segment column is configured, a pandas.DataFrame with evaluation metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_feature_importances()¶

Return the feature importances.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping each importance metric to an OrderedDict of {feature_name: value}. If a segment column is configured, a pandas.DataFrame with feature importances for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_performance_metrics()¶

Return the performance metrics of the last trained model.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary with metric name as key and metric value as value. If a segment column is configured, a pandas.DataFrame with performance metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

Examples

>>> data = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')
>>> model = GradientBoostingBinaryClassifier(conn)
>>> model.fit(data=data, key='id', label='class')
>>> model.get_performance_metrics()
{'AUC': 0.9385, 'PredictivePower': 0.8529, 'PredictionConfidence': 0.9759, ...}

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

predict(data, prediction_type=None)¶

Make predictions with the fitted model.

Parameters

dataDataFrame

The input dataset used for prediction.

prediction_typestr, optional

The type of output to generate:

'BestProbabilityAndDecision' — return the probability associated with the classification decision (default).
'Decision' — return the classification decision only.
'Probability' — return the probability that the row is a positive target (binary classification) or the probabilities of all classes (multiclass).
'Score' — return raw prediction scores.
'Individual Contributions' — return SHAP values.
'Explanations' — return strength indicators based on SHAP values.

Returns

DataFrame: The prediction output.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_framework_version(framework_version)¶

Switch v1/v2 version of report.

Parameters

framework_version{'v2', 'v1'}, optional

v2: using report builder framework. v1: using pure html template.

Defaults to 'v2'.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

set_shapley_explainer_of_predict_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

A ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

set_shapley_explainer_of_score_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

A ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

class hana_ml.algorithms.apl.gradient_boosting_classification.GradientBoostingBinaryClassifier(conn_context=None, early_stopping_patience=None, eval_metric=None, learning_rate=None, max_depth=None, max_iterations=None, number_of_jobs=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, target_key=None, interactions=None, interactions_max_kept=None, variable_auto_selection=None, variable_selection_max_nb_of_final_variables=None, variable_selection_max_iterations=None, variable_selection_percentage_of_contribution_kept_by_step=None, variable_selection_quality_bar=None, cutting_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: _GradientBoostingClassifierBase

SAP HANA APL Gradient Boosting Binary Classifier algorithm.

Very similar to GradientBoostingClassifier, but provides metrics specific to binary classification.

Parameters

conn_contextConnectionContext, optional

The connection object to an SAP HANA database. This parameter is not needed anymore. It will be set automatically when a dataset is used in fit() or predict().

early_stopping_patienceint, optional

If the performance does not improve after early_stopping_patience iterations, training stops before reaching max_iterations. Default is 10.

eval_metricstr, optional

The metric used to evaluate model performance on the validation dataset along the boosting iterations. The possible values are 'LogLoss', 'AUC', and 'ClassificationError'. Default is 'LogLoss'.

learning_ratefloat, optional

The shrinkage factor applied to each tree's contribution during boosting. A smaller value reduces the step size at each iteration, which typically requires more iterations to converge but can improve the robustness of the model. Default is 0.1.

max_depthint, optional

The maximum depth of the decision trees added as a base learner at each boosting iteration. Default is 4.

max_iterationsint, optional

The maximum number of boosting iterations to fit the model. Default is 1000.

number_of_jobsint, optional

Deprecated.

variable_storagesdict, optional

Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.

variable_value_typesdict, optional

Specifies the variable value type (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.

variable_missing_stringsdict, optional

Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.

extra_applyout_settingsdict, optional

Determines the output of the predict() method. These settings can also be passed directly as the prediction_type argument of predict(). The possible values are:

By default (None): the default output columns are:
- <KEY> — the key column if provided in the dataset.
- TRUE_LABEL — the class label if provided in the dataset.
- PREDICTED — the predicted label.
- PROBABILITY — the probability of the prediction.
{'APL/ApplyExtraMode': 'Individual Contributions'} — SHAP-based feature contribution for each sample:
- <KEY> — the key column if provided.
- TRUE_LABEL — the class label if provided.
- PREDICTED — the predicted label.
- gb_contrib_<VAR1> — the contribution of variable VAR1 to the score.
- ...
- gb_contrib_<VARN> — the contribution of variable VARN to the score.
- gb_contrib_constant_bias — the constant bias contribution.

max_tasksint, optional

Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.

segment_column_namestr, optional

Name of the column containing the segment key, enabling one-model-per-segment training.

target_keystr, optional

Value of the target variable to treat as the positive class. Defaults to the least frequent category.

interactionsbool, optional

If True, activates computation of SHAP interaction values between variables. Default is False.

interactions_max_keptint, optional

Maximum number of interactions to keep per variable. Default is 5.

variable_auto_selectionbool, optional

If True, automatically reduces the number of variables while maintaining model quality. Default is False.

variable_selection_max_nb_of_final_variablesint, optional

Maximum number of variables to retain in the final model. -1 keeps all variables. Default is -1.

variable_selection_max_iterationsint, optional

Maximum number of variable selection iterations. Default is 2.

variable_selection_percentage_of_contribution_kept_by_stepfloat, optional

Fraction of information to retain at each selection step. Default is 0.90.

variable_selection_quality_barfloat, optional

Maximum accepted absolute Area Under the ROC Curve difference between the initial model (trained with all input variables) and the model resulting from the variable selection process. A higher value results in fewer retained variables. Default is 0.01.

cutting_strategystr, optional

Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.

other_train_apl_aliasesdict, optional

Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

labelstr: The target column name. Set when fit() is called.
model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`build_report`([max_local_explanations])	Build and store the model HTML report.
`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, label, weight, ...])	Fit the model.
`generate_html_report`(filename)	Save model report as a html file.
`generate_notebook_iframe_report`()	Render model report as a notebook iframe.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_best_iteration`()	Return the iteration that provided the best performance on the validation dataset.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_evalmetrics`()	Return the values of the evaluation metric at each training iteration.
`get_feature_importances`()	Return the feature importances.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the last trained model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data[, prediction_type])	Make predictions with the fitted model.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`score`(data)	Compute the accuracy score on the provided test dataset.
`set_framework_version`(framework_version)	Switch v1/v2 version of report.
`set_metric_samplings`([roc_sampling, ...])	Set metric samplings to report builder.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.
`set_shapley_explainer_of_predict_phase`(...)	Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.
`set_shapley_explainer_of_score_phase`(...[, ...])	Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. The key is particularly useful to join the predictions output to the input dataset.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(hana_df, label='class', key='id')

Getting variable interactions

>>> model.set_params(interactions=True, interactions_max_kept=3)
>>> model.fit(data=hana_df, key='id', label='class')
>>> # Checks interaction info in INDICATORS table
>>> output = model.get_indicators().filter("KEY LIKE 'Interaction%'").collect()

Debriefing

>>> # Global performance metrics of the model
>>> model.get_performance_metrics()
{'LogLoss': 0.2567069689038737, 'PredictivePower': 0.8529, 'PredictionConfidence': 0.9759, ...}

>>> model.get_feature_importances()
{'Gain': OrderedDict([('relationship', 0.3866586685180664), ('education-num', 0.1502334326505661), ...]), ...}

Generating the model report

>>> from hana_ml.visualizers.unified_report import UnifiedReport
>>> UnifiedReport(model).build().display()

Making predictions

>>> # Default output
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().sample(3) # returns the output as a pandas DataFrame
          id  TRUE_LABEL  PREDICTED  PROBABILITY
44903  41211           0          0     0.871326
47878  36020           1          1     0.993455
17549   6601           0          1     0.673872

>>> # Individual Contributions
>>> model.set_params(extra_applyout_settings={'APL/ApplyExtraMode': 'Individual Contributions'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().sample(3) # returns the output as a pandas DataFrame
      id  TRUE_LABEL  gb_contrib_age  gb_contrib_workclass  gb_contrib_fnlwgt  ...
0  18448           0       -1.098452             -0.001238           0.060850  ...
1  18457           0       -0.731512             -0.000448           0.020060  ...
2  18540           0       -0.024523              0.027065           0.158083  ...

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> from hana_ml.model_storage import ModelStorage
>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Reloading the model for new predictions

>>> model2 = model_storage.load_model(name='My model name')
>>> out2 = model2.predict(data=hana_df)

Exporting the model in JSON format

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: The attribute names and values.

Returns

self: The updated model instance.

score(data)¶

Compute the accuracy score on the provided test dataset.

Parameters

dataDataFrame: The test dataset used to compute the score. The labels must be provided in the dataset.

Returns

float or pandas.DataFrame: If no segment column is given, the accuracy score. If a segment column is given, a pandas.DataFrame with the accuracy score for each segment.

build_report(max_local_explanations=100)¶

Build and store the model HTML report.

This method only prepares and stores the report data internally. Call generate_html_report() or generate_notebook_iframe_report() afterwards to render or export it.

Parameters

max_local_explanationsint, optional: Maximum number of local explanations displayed in the report. Default is 100. Only effective when predict() was called before build_report() with prediction_type='Explanations'. Has no effect otherwise.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

fit(data, key=None, features=None, label=None, weight=None, build_report=False)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. This is not recommended. See notes below.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all non-ID and non-label columns will be used.
labelstr, optional: The name of the label column. Default is the last column.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.
build_reportbool, optional: Whether to build the model HTML report after training. Default is False.

Returns

self: The fitted model instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. That is particularly inconvenient to join the predictions output to the input dataset.

generate_html_report(filename)¶

Save model report as a html file.

Parameters

filenamestr: Html file name.

generate_notebook_iframe_report()¶: Render model report as a notebook iframe.

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_best_iteration()¶

Return the iteration that provided the best performance on the validation dataset.

Returns

int or pandas.DataFrame: If no segment column is configured, the best iteration as an integer. If a segment column is configured, a pandas.DataFrame with the best iteration for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_evalmetrics()¶

Return the values of the evaluation metric at each training iteration.

These values are computed on the validation dataset.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping metric name to a list of values, one per iteration: {'<MetricName>': [<value>, ...]}. If a segment column is configured, a pandas.DataFrame with evaluation metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_feature_importances()¶

Return the feature importances.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping each importance metric to an OrderedDict of {feature_name: value}. If a segment column is configured, a pandas.DataFrame with feature importances for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_performance_metrics()¶

Return the performance metrics of the last trained model.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary with metric name as key and metric value as value. If a segment column is configured, a pandas.DataFrame with performance metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

Examples

>>> data = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')
>>> model = GradientBoostingBinaryClassifier(conn)
>>> model.fit(data=data, key='id', label='class')
>>> model.get_performance_metrics()
{'AUC': 0.9385, 'PredictivePower': 0.8529, 'PredictionConfidence': 0.9759, ...}

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

predict(data, prediction_type=None)¶

Make predictions with the fitted model.

Parameters

dataDataFrame

The input dataset used for prediction.

prediction_typestr, optional

The type of output to generate:

'BestProbabilityAndDecision' — return the probability associated with the classification decision (default).
'Decision' — return the classification decision only.
'Probability' — return the probability that the row is a positive target (binary classification) or the probabilities of all classes (multiclass).
'Score' — return raw prediction scores.
'Individual Contributions' — return SHAP values.
'Explanations' — return strength indicators based on SHAP values.

Returns

DataFrame: The prediction output.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_framework_version(framework_version)¶

Switch v1/v2 version of report.

Parameters

framework_version{'v2', 'v1'}, optional

v2: using report builder framework. v1: using pure html template.

Defaults to 'v2'.

set_metric_samplings(roc_sampling: Sampling = None, other_samplings: dict = None)¶

Set metric samplings to report builder.

Parameters

roc_samplingSampling, optional

ROC sampling.

other_samplingsdict, optional

Key is column name of metric table.

CUMGAINS

RANDOM_CUMGAINS

PERF_CUMGAINS

LIFT

RANDOM_LIFT

PERF_LIFT

CUMLIFT

RANDOM_CUMLIFT

PERF_CUMLIFT

Value is sampling.

Examples

Creating the metric samplings:

>>> roc_sampling = Sampling(method='every_nth', interval=2)

>>> other_samplings = dict(CUMGAINS=Sampling(method='every_nth', interval=2),
                      LIFT=Sampling(method='every_nth', interval=2),
                      CUMLIFT=Sampling(method='every_nth', interval=2))
>>> model.set_metric_samplings(roc_sampling, other_samplings)

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

set_shapley_explainer_of_predict_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

A ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

set_shapley_explainer_of_score_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

A ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

hana_ml.algorithms.apl.gradient_boosting_regression¶

This module provides the SAP HANA APL gradient boosting regression algorithm.

The following classes are available:

GradientBoostingRegressor

class hana_ml.algorithms.apl.gradient_boosting_regression.GradientBoostingRegressor(conn_context=None, early_stopping_patience=None, eval_metric=None, learning_rate=None, max_depth=None, max_iterations=None, number_of_jobs=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, interactions=None, interactions_max_kept=None, variable_auto_selection=None, variable_selection_max_nb_of_final_variables=None, variable_selection_max_iterations=None, variable_selection_percentage_of_contribution_kept_by_step=None, variable_selection_quality_bar=None, cutting_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: GradientBoostingBase, _UnifiedRegressionReportBuilder

SAP HANA APL Gradient Boosting Regression algorithm.

Parameters

conn_contextConnectionContext, optional

The connection object to an SAP HANA database. This parameter is not needed anymore. It will be set automatically when a dataset is used in fit() or predict().

early_stopping_patienceint, optional

If the performance does not improve after early_stopping_patience iterations, training stops before reaching max_iterations. Default is 10.

eval_metricstr, optional

The metric used to evaluate model performance on the validation dataset along the boosting iterations. The possible values are 'MAE' and 'RMSE'. Default is 'RMSE'.

learning_ratefloat, optional

The shrinkage factor applied to each tree's contribution during boosting. A smaller value reduces the step size at each iteration, which typically requires more iterations to converge but can improve the robustness of the model. Default is 0.1.

max_depthint, optional

The maximum depth of the decision trees added as a base learner at each boosting iteration. Default is 4.

max_iterationsint, optional

The maximum number of boosting iterations to fit the model. Default is 1000.

number_of_jobsint, optional

Deprecated.

variable_storagesdict, optional

Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.

variable_value_typesdict, optional

Specifies the variable value types (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.

variable_missing_stringsdict, optional

Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.

extra_applyout_settingsdict, optional

Determines the output of the predict() method. These settings can also be passed directly as the prediction_type argument of predict(). The possible values are:

By default (None): the default output columns are:
- <KEY> — the key column if provided in the dataset.
- TRUE_LABEL — the actual value if provided.
- PREDICTED — the predicted value.
{'APL/ApplyExtraMode': 'Individual Contributions'} — SHAP-based feature contribution for each sample:
- <KEY> — the key column if provided.
- TRUE_LABEL — the actual value if provided.
- PREDICTED — the predicted value.
- gb_contrib_<VAR1> — the contribution of variable VAR1 to the score.
- ...
- gb_contrib_<VARN> — the contribution of variable VARN to the score.
- gb_contrib_constant_bias — the constant bias contribution.

max_tasksint, optional

Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.

segment_column_namestr, optional

Name of the column containing the segment key, enabling one-model-per-segment training.

interactionsbool, optional

If True, activates computation of SHAP interaction values between variables. Default is False.

interactions_max_keptint, optional

Maximum number of interactions to keep per variable. Default is 5.

variable_auto_selectionbool, optional

If True, automatically reduces the number of variables while maintaining model quality. Default is False.

variable_selection_max_nb_of_final_variablesint, optional

Maximum number of variables to retain in the final model. -1 keeps all variables. Default is -1.

variable_selection_max_iterationsint, optional

Maximum number of variable selection iterations. Default is 2.

variable_selection_percentage_of_contribution_kept_by_stepfloat, optional

Fraction of information to retain at each selection step. Default is 0.90.

variable_selection_quality_barfloat, optional

Maximum accepted relative RMSE difference between the initial model (trained with all input variables) and the model resulting from the variable selection process. A higher value results in fewer retained variables. Default is 0.01.

cutting_strategystr, optional

Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.

other_train_apl_aliasesdict, optional

Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

labelstr: The target column name. Set when fit() is called. Must be set explicitly before calling predict() when the model is loaded from a table.
model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`build_report`([max_local_explanations])	Build and store the model HTML report.
`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, label, weight, ...])	Fit the model.
`generate_html_report`(filename)	Save model report as a html file.
`generate_notebook_iframe_report`()	Render model report as a notebook iframe.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_best_iteration`()	Return the iteration that provided the best performance on the validation dataset.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_evalmetrics`()	Return the values of the evaluation metric at each training iteration.
`get_feature_importances`()	Return the feature importances.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the last trained model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data[, prediction_type])	Make predictions with the fitted model.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`score`(data)	Compute the R2 score (coefficient of determination) on the provided test dataset.
`set_framework_version`(framework_version)	Switch v1/v2 version of report.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.
`set_shapley_explainer_of_predict_phase`(...)	Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.
`set_shapley_explainer_of_score_phase`(...[, ...])	Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. The key is particularly useful to join the predictions output to the input dataset.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_regression import GradientBoostingRegressor
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn,
...                     'SELECT "id", "class", "capital-gain", '
...                     '"native-country", "age" FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = GradientBoostingRegressor()
>>> model.fit(hana_df, label='age', key='id')

Getting variable interactions

>>> model.set_params(interactions=True, interactions_max_kept=3)
>>> model.fit(data=hana_df, key='id', label='age')
>>> # Checks interaction info in INDICATORS table
>>> output = model.get_indicators().filter("KEY LIKE 'Interaction%'").collect()

Debriefing

>>> # Global performance metrics of the model
>>> model.get_performance_metrics()
{'L1': 7.31774, 'MeanAbsoluteError': 7.31774, 'L2': 9.42497, 'RootMeanSquareError': 9.42497, ...}

>>> model.get_feature_importances()
{'Gain': OrderedDict([('class', 0.8728259801864624), ('capital-gain', 0.10493823140859604), ...]), ...}

Generating the model report

>>> from hana_ml.visualizers.unified_report import UnifiedReport
>>> UnifiedReport(model).build().display()

Making predictions

>>> # Default output
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().head(3) # returns the output as a pandas DataFrame
          id  TRUE_LABEL  PREDICTED
39184  21772          27         25
16537   7331          33         43
7908   35226          65         42

>>> # Individual contributions
>>> model.set_params(extra_applyout_settings={'APL/ApplyExtraMode': 'Individual Contributions'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect().head(3) # returns the output as a pandas DataFrame
     id  TRUE_LABEL  gb_contrib_workclass  gb_contrib_fnlwgt  gb_contrib_education  ...
0  6241          21             -1.330736          -0.385088              0.373539  ...
1  6248          18             -0.784536          -2.191791             -1.788672  ...
2  6253          26             -0.773891           0.358133             -0.185864  ...

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> from hana_ml.model_storage import ModelStorage
>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Reloading the model for new predictions

>>> model2 = model_storage.load_model(name='My model name')
>>> out2 = model2.predict(data=hana_df)

Exporting the model in JSON format

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: Keyword arguments where each key is an attribute name and the value is the new attribute value.

Returns

self: The updated model instance.

predict(data, prediction_type=None)¶

Make predictions with the fitted model.

Parameters

dataDataFrame

The input dataset used for prediction.

prediction_typestr, optional

The type of output to generate:

'Score' — return predicted value (default).
'Individual Contributions' — return SHAP values.
'Explanations' — return strength indicators based on SHAP values.

Returns

DataFrame: The prediction output with columns <key column name>, TRUE_LABEL, PREDICTED, and any extra columns depending on prediction_type.

Raises

FitIncompleteError: If fit() has not been called yet.

score(data)¶

Compute the R2 score (coefficient of determination) on the provided test dataset.

Parameters

dataDataFrame: The test dataset. Labels must be included.

Returns

float or pandas.DataFrame: If no segment column is configured, the R2 score as a float. If a segment column is configured, a pandas.DataFrame with the R2 score for each segment.

build_report(max_local_explanations=100)¶

Build and store the model HTML report.

This method only prepares and stores the report data internally. Call generate_html_report() or generate_notebook_iframe_report() afterwards to render or export it.

Parameters

max_local_explanationsint, optional: Maximum number of local explanations displayed in the report. Default is 100. Only effective when predict() was called before build_report() with prediction_type='Explanations'. Has no effect otherwise.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

fit(data, key=None, features=None, label=None, weight=None, build_report=False)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. This is not recommended. See notes below.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all non-ID and non-label columns will be used.
labelstr, optional: The name of the label column. Default is the last column.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.
build_reportbool, optional: Whether to build the model HTML report after training. Default is False.

Returns

self: The fitted model instance.

Notes

It is highly recommended to specify a key column in the training dataset. If not, once the model is trained, it will not be possible anymore to have a key defined in any input dataset. That is particularly inconvenient to join the predictions output to the input dataset.

generate_html_report(filename)¶

Save model report as a html file.

Parameters

filenamestr: Html file name.

generate_notebook_iframe_report()¶: Render model report as a notebook iframe.

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_best_iteration()¶

Return the iteration that provided the best performance on the validation dataset.

Returns

int or pandas.DataFrame: If no segment column is configured, the best iteration as an integer. If a segment column is configured, a pandas.DataFrame with the best iteration for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_evalmetrics()¶

Return the values of the evaluation metric at each training iteration.

These values are computed on the validation dataset.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping metric name to a list of values, one per iteration: {'<MetricName>': [<value>, ...]}. If a segment column is configured, a pandas.DataFrame with evaluation metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_feature_importances()¶

Return the feature importances.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary mapping each importance metric to an OrderedDict of {feature_name: value}. If a segment column is configured, a pandas.DataFrame with feature importances for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_performance_metrics()¶

Return the performance metrics of the last trained model.

Returns

dict or pandas.DataFrame: If no segment column is configured, a dictionary with metric name as key and metric value as value. If a segment column is configured, a pandas.DataFrame with performance metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

Examples

>>> data = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')
>>> model = GradientBoostingBinaryClassifier(conn)
>>> model.fit(data=data, key='id', label='class')
>>> model.get_performance_metrics()
{'AUC': 0.9385, 'PredictivePower': 0.8529, 'PredictionConfidence': 0.9759, ...}

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_framework_version(framework_version)¶

Switch v1/v2 version of report.

Parameters

framework_version{'v2', 'v1'}, optional

v2: using report builder framework. v1: using pure html template.

Defaults to 'v2'.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

set_shapley_explainer_of_predict_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the prediction phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

set_shapley_explainer_of_score_phase(shapley_explainer, display_force_plot=True)¶

Use the reason code generated during the scoring phase to build a ShapleyExplainer instance.

When this instance is passed in, the execution results of this instance will be included in the report of v2 version.

Parameters

shapley_explainerShapleyExplainer

ShapleyExplainer instance.

display_force_plotbool, optional

Whether to display the force plot.

Defaults to True.

hana_ml.algorithms.apl.time_series¶

This module contains the SAP HANA APL Time Series algorithm.

The following class is available:

AutoTimeSeries

class hana_ml.algorithms.apl.time_series.AutoTimeSeries(conn_context=None, time_column_name=None, target=None, horizon=1, with_extra_predictable=True, last_training_time_point=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, train_data_=None, sort_data=True, max_tasks=None, segment_column_name=None, force_negative_forecast=None, force_positive_forecast=None, forecast_fallback_method=None, forecast_max_cyclics=None, forecast_max_lags=None, forecast_method=None, smoothing_cycle_length=None, other_train_apl_aliases=None, **other_params)¶

Bases: APLBase

SAP HANA APL Time Series algorithm.

Parameters

time_column_namestr, optional: The name of the column containing the time series time points. The time column is used as table key. It can be overridden by setting the key parameter through the fit() method.
targetstr, optional: The name of the column containing the time series data points. When only two columns are present in the dataset, the target is automatically inferred as the non-time column.
last_training_time_pointstr, optional: The last time point used for model training. The training dataset will contain all data points up to this date. By default, this parameter will be set as the last time point until which the target is not null.
horizonint, optional: The number of forecasts to be generated by the model upon apply. The time series model will be trained to optimize accuracy on the requested horizon only. Default is 1.
with_extra_predictablebool, optional: If set to True, all input variables will be used by the model to generate forecasts. If set to False, only the time and target columns will be used. All other variables will be ignored. Default is True.
variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.
variable_value_typesdict, optional: Specifies the variable value types (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
extra_applyout_settingsdict, optional: Warning

This parameter is deprecated. Please use the prediction_type parameter of predict(), forecast(), and fit_predict() instead.
sort_databool, optional: If True, a temporary view is created on the dataset to sort data by time. However, users can provide directly a view with sorted dates. In this case, they must set sort_data to False to avoid creating a new view. Default is True.

Warning

It is recommended to leave this parameter at its default so the data is guaranteed to be read in sorted order. If the data is not sorted, the model will fail.
max_tasksint, optional: Maximum number of parallel tasks during training and forecasting. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
force_negative_forecastbool, optional: If True, replaces all positive forecast values with zero. Default is False.
force_positive_forecastbool, optional: If True, replaces all negative forecast values with zero. Default is False.
forecast_methodstr, optional: Override the default forecasting algorithm. Accepted values: 'Default', 'LinearRegression', 'ExponentialSmoothing'. Default is 'Default'.
forecast_fallback_methodstr, optional: Method used when forecast_method fails (e.g. too few data points). Accepted values: 'LinearRegression', 'ExponentialSmoothing'. Default is 'ExponentialSmoothing'.
forecast_max_cyclicsint, optional: Maximum cycle length (in periods) that the algorithm tries to detect. Set to 0 to disable cyclic analysis entirely. Default is 200.
forecast_max_lagsint, optional: Maximum autoregressive lag considered during fluctuation analysis. Set to 0 to disable fluctuation analysis. Default is one quarter of the estimation dataset size.
smoothing_cycle_lengthint, optional: Overrides the cycle/seasonal length used for smoothing, instead of the value automatically inferred from the time granularity (e.g. 4 for quarterly, 12 for yearly).
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.
train_data_DataFrame: The training dataset.

Methods

`build_report`([segment_name, ...])	Build and store the model HTML report.
`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, build_report])	Fit the model.
`fit_predict`(data[, key, features, horizon, ...])	Fit a model and generate forecasts in a single call to APL.
`forecast`([forecast_length, data, ...])	Use the fitted model to generate out-of-sample forecasts.
`generate_html_report`(filename)	Save the model report as an HTML file.
`generate_notebook_iframe_report`()	Render the model report as an iframe in a Jupyter notebook.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_horizon_wide_metric`([metric_name])	Return the value of a performance metric averaged over the forecast horizon.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_components`()	Return the description of the model components used to generate forecasts.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Load the model from a table.
`predict`(data[, apply_horizon, ...])	Use the fitted model to generate forecasts.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

The input dataset, given as a DataFrame, must not be a temporary table because the API tries to create a view sorted by the time column. SAP HANA does not allow users to create a view on a temporary table. However, even though it is not recommended, to avoid creating the view, the user can force sort_data to False.

When calling the fit_predict() method, the time series model is generated on the fly and not returned. If the model must be saved, use the fit() method instead.

When extra-predictable variables are involved, it is usual to have a single dataset used both for the model training and the forecasting. In this case, the dataset should contain two successive periods:

The first one is used for the model training, ranging from the beginning to the last date where the target value is not null.
The second one is used for forecasting, ranging from the first date where the target value is null.

The content of the output of get_performance_metrics() may change depending on the version of SAP HANA APL used with this API. Please refer to the SAP HANA APL documentation to know which metrics will be provided.

Examples

>>> from hana_ml.algorithms.apl.time_series import AutoTimeSeries
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CASHFLOWS_FULL')

Creating and fitting the model

>>> model = AutoTimeSeries(time_column_name='Date', target='Cash', horizon=3)
>>> model.fit(data=hana_df)

Debriefing

>>> model.get_model_components()
{'Trend': 'Polynom( Date)',
 'Cycles': 'PeriodicExtrasPred_MondayMonthInd',
 'Fluctuations': 'AR(46)'}

>>> model.get_performance_metrics()
{'MAPE': [0.12853715702893018, 0.12789963348617622, 0.12969031859857874], ...}

Generating forecasts using the forecast() method

This method is used to generate forecasts using a signature similar to the one used in PAL. There are two variants of usage as described below:

1) If the model does not use extra-predictable variables (no exogenous variable), users must simply specify the number of forecasts.

>>> train_df = DataFrame(conn,
                         'SELECT "Date", "Cash" '
                         'FROM APL_SAMPLES.CASHFLOWS_FULL ORDER BY 1 LIMIT 100')
>>> model = AutoTimeSeries(time_column_name='Date', target='Cash', horizon=3)
>>> model.fit(train_df)
>>> out = model.forecast(forecast_length=3)
>>> out.collect().tail(5)
           Date                            ACTUAL    PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
98   2001-05-23  3057.812544999999772699132909775  4593.966530              NaN              NaN
99   2001-05-25  3037.539714999999887176132440567  4307.893346              NaN              NaN
100  2001-05-26                              None  4206.023158     -3609.599872     12021.646187
101  2001-05-27                              None  4575.162651     -3392.283802     12542.609104
102  2001-05-28                              None  4830.352462     -3239.507360     12900.212284

2) If the model uses extra-predictable variables, users must provide the values of all extra-predictable variables for each time point of the forecast period. These values must be provided as a DataFrame with the same structure as the training dataset.

>>> # Trains the dataset with extra-predictable variables
>>> train_df = DataFrame(conn,
...                      'SELECT * '
...                      'FROM APL_SAMPLES.CASHFLOWS_FULL '
...                      'WHERE "Cash" IS NOT NULL')
>>> # Extra-predictable variables' values on the forecast period
>>> forecast_df = DataFrame(conn,
...                         'SELECT * '
...                         'FROM APL_SAMPLES.CASHFLOWS_FULL '
...                         'WHERE "Cash" IS NULL LIMIT 5')
>>> model = AutoTimeSeries(time_column_name='Date', target='Cash', horizon=3)
>>> model.fit(train_df)
>>> out = model.forecast(data=forecast_df)
>>> out.collect().tail(5)
           Date ACTUAL    PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
251  2001-12-29   None  6864.371407      -224.079492     13952.822306
252  2001-12-30   None  6889.515324      -211.264912     13990.295559
253  2001-12-31   None  6914.766513      -187.180923     14016.713949
254  2002-01-01   None  6940.124974              NaN              NaN
255  2002-01-02   None  6965.590706              NaN              NaN

Generating forecasts with the predict() method

The predict() method allows users to apply a fitted model on a dataset different from the training dataset. For example, users can train a dataset on the first quarter (January to March) and apply the model on a dataset of different period (March to May).

>>> # Trains the model on the first quarter, from January to March
>>> train_df = DataFrame(conn,
...                      'SELECT "Date", "Cash" '
...                      'FROM APL_SAMPLES.CASHFLOWS_FULL '
...                      "WHERE "Date" BETWEEN '2001-01-01' AND '2001-03-31' "
...                      'ORDER BY 1')
>>> model.fit(train_df)
>>> # Forecasts on a shifted period, from March to May
>>> test_df = DataFrame(conn,
...                     'SELECT "Date", "Cash" '
...                     'FROM APL_SAMPLES.CASHFLOWS_FULL '
...                     "WHERE "Date" BETWEEN '2001-03-01' AND '2001-05-31' "
...                     'ORDER BY 1')
>>> out = model.predict(test_df)
>>> out.collect().tail(5)
          Date                            ACTUAL     PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
60  2001-05-30  3837.196734000000105879735597214   4630.223083              NaN              NaN
61  2001-05-31  2911.884261000000151398126928726   4635.265982              NaN              NaN
62  2001-06-01                              None   4538.516542     -1087.461104     10164.494188
63  2001-06-02                              None   4848.815364     -5090.167255     14787.797983
64  2001-06-03                              None   4853.858263     -5138.553275     14846.269801

Using the fit_predict() method

This method enables the user to fit a model and generate forecasts on a single call, and thus get results faster. However, the model is created on the fly and deleted after use, so the user will not be able to save the resulting model.

>>> out = model.fit_predict(hana_df)
>>> out.collect().tail(5)
           Date            ACTUAL    PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
249  2001-12-27  5995.42329499999  6055.761105              NaN              NaN
250  2001-12-28  7111.41669699999  6314.336098              NaN              NaN
251  2002-01-03              None  7033.880804      4529.462710      9538.298899
252  2002-01-04              None  6464.557223      3965.343397      8963.771049
253  2002-01-07              None  6469.141663      3961.414900      8976.868427

Breaking down the time series into components (trend, cycles, fluctuations)

Pass prediction_type='Stable Components and Error Bars' to any forecast method to obtain decomposition columns alongside the forecast. Each output column is suffixed with the horizon index, e.g. Trend_1 is the trend component of the first horizon and Trend_RESIDUALS_1 its residual.

>>> model.fit(train_df)
>>> out = model.predict(hana_df,
...                     prediction_type='Stable Components and Error Bars')
>>> out.collect().tail(5)
           Date                  ACTUAL        ...  Cycles_RESIDUALS_3  Fluctuations_RESIDUALS_3
249  2001-12-27  5995.42329499392507553        ...               32.51                  4.48e-13
250  2001-12-28  7111.41669699455205917        ...             -644.77                  1.14e-13
251  2002-01-03                    None        ...                 NaN                       NaN
252  2002-01-04                    None        ...                 NaN                       NaN
253  2002-01-07                    None        ...                 NaN                       NaN

Use prediction_type='First Forecast with Stable Components and Residues and Error Bars' to obtain a single-horizon decomposition into trend, cycles, extra predictable variables, and fluctuations contributions, together with a global residual and a 95% confidence interval.

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: Attribute names and values as keyword arguments.

Returns

self: The updated model instance.

fit(data, key=None, features=None, build_report=False)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The column used as row identifier of the dataset. This column corresponds to the time column name. As a result, setting this parameter will overwrite the time_column_name model setting.
featureslist of str, optional: The names of the feature columns, meaning the date column and the extra-predictive variables. If features is not provided, it defaults to all columns except the target column.
build_reportbool, optional: Whether to build the model HTML report after training. Default is False.

Returns

self: The fitted model instance.

predict(data, apply_horizon=None, apply_last_time_point=None, build_report=False, prediction_type=None)¶

Use the fitted model to generate forecasts.

Parameters

dataDataFrame

The input dataset used for predictions.

apply_horizonint, optional

The number of forecasts to generate. By default, the number of forecasts is the horizon on which the model was trained.

apply_last_time_pointstr, optional

The time point corresponding to the start of the forecast period. Forecasts will be generated starting from the next time point after the apply_last_time_point. By default, this parameter is set to the value of last_training_time_point known from the model training.

build_reportbool, optional

Whether to build the model HTML report after prediction. Default is False.

prediction_typestr, optional

Controls the content of the prediction output. Accepted values:

'No Extra' — forecast values for all horizons, without confidence interval.
'Forecasts and Error Bars' — forecast value for the nearest horizon with a 95% confidence interval.
'Stable Components and Error Bars' — forecast values for all horizons, each decomposed into trend, cycles, and fluctuations with their residuals, plus a 95% confidence interval on the nearest horizon.
'First Forecast with Stable Components and Residues and Error Bars' — forecast for the nearest horizon with a 95% confidence interval, decomposed into trend, cycles, extra predictable variables, and fluctuations contributions, plus a single global residual.

Additional values are described in the APL/ApplyExtraMode reference.

Default is 'Forecasts and Error Bars'. When build_report=True, this parameter is overridden and 'First Forecast with Stable Components and Residues and Error Bars' is used automatically to supply all data required by the report.

Returns

DataFrame: Always contains the time column and ACTUAL (the observed value). Additional columns depend on prediction_type.

Examples

Default output

>>> out = model.predict(hana_df)
>>> out.collect().tail(5)
           Date            ACTUAL    PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
249  2001-12-27  5995.42329499999   6055.76110              NaN              NaN
250  2001-12-28  7111.41669699999   6314.33609              NaN              NaN
251  2002-01-03              None   7033.88080       4529.46271       9538.29889
252  2002-01-04              None   6464.55722       3965.34339       8963.77104
253  2002-01-07              None   6469.14166       3961.41490       8976.86842

Retrieving forecasts with components (trend, cycles, fluctuations) and residuals

Output columns are suffixed with the horizon index, e.g. Trend_1 is the trend component of the first horizon and Trend_RESIDUALS_1 its residual.

>>> out = model.predict(hana_df,
...                     prediction_type='Stable Components and Error Bars')
>>> out.collect().tail(5)
           Date                               ACTUAL  PREDICTED_1      Trend_1  ...
249  2001-12-27  5995.423294999999598076101392507553  6055.761105  6814.405390  ...
250  2001-12-28  7111.416696999999658146407455205917  6314.336098  6839.334762  ...
251  2002-01-03                                 None  7033.880804  6991.163710  ...
252  2002-01-04                                 None  6464.557223  7016.843985  ...
253  2002-01-07                                 None  6469.141663  7094.528433  ...

fit_predict(data, key=None, features=None, horizon=None, build_report=False, prediction_type=None)¶

Fit a model and generate forecasts in a single call to APL.

This method offers a faster way to perform the model training and forecasting. However, the user will not have access to the model used internally since it is deleted after the computation of the forecasts.

Parameters

dataDataFrame

The input time series dataset.

keystr, optional

The date column name. By default, it is equal to the model parameter time_column_name. If provided, the model parameter time_column_name will be overwritten.

featureslist of str, optional

The column names corresponding to the extra-predictable variables (exogenous variables). If features is not provided, it defaults to all columns except the target column.

horizonint, optional

The number of forecasts to generate. Default is the horizon parameter of the model.

build_reportbool, optional

Whether to build the model HTML report after prediction. Default is False.

prediction_typestr, optional

Controls the content of the prediction output. Accepted values:

'No Extra' — forecast values for all horizons, without confidence interval.
'Forecasts and Error Bars' — forecast value for the nearest horizon with a 95% confidence interval.
'Stable Components and Error Bars' — forecast values for all horizons, each decomposed into trend, cycles, and fluctuations with their residuals, plus a 95% confidence interval on the nearest horizon.
'First Forecast with Stable Components and Residues and Error Bars' — forecast for the nearest horizon with a 95% confidence interval, decomposed into trend, cycles, extra predictable variables, and fluctuations contributions, plus a single global residual.

Additional values are described in the APL/ApplyExtraMode reference.

Default is 'Forecasts and Error Bars'. When build_report=True, this parameter is overridden and 'First Forecast with Stable Components and Residues and Error Bars' is used automatically to supply all data required by the report.

Returns

DataFrame: Always contains the time column and ACTUAL (the observed value). Additional columns depend on prediction_type.

forecast(forecast_length=None, data=None, build_report=False, prediction_type=None)¶

Use the fitted model to generate out-of-sample forecasts.

The model must already be fitted with a training dataset. This method forecasts over a number of steps after the end of the training dataset. When there are extra-predictive variables (exogenous variables), the data parameter is required. It must contain the values of the extra-predictable variables for the forecast period. If there are no extra-predictive variables, only the forecast_length parameter is needed.

Parameters

forecast_lengthint, optional

The number of forecasts to generate from the end of the training dataset. Default is horizon.

dataDataFrame, optional

The time series with extra-predictable variables used for forecasting. Required if extra-predictive variables are used in the model. When this parameter is given, the forecast_length parameter is ignored.

build_reportbool, optional

Whether to build the model HTML report after forecasting. Default is False.

prediction_typestr, optional

Controls the content of the prediction output. Accepted values:

'No Extra' — forecast values for all horizons, without confidence interval.
'Forecasts and Error Bars' — forecast value for the nearest horizon with a 95% confidence interval.
'Stable Components and Error Bars' — forecast values for all horizons, each decomposed into trend, cycles, and fluctuations with their residuals, plus a 95% confidence interval on the nearest horizon.
'First Forecast with Stable Components and Residues and Error Bars' — forecast for the nearest horizon with a 95% confidence interval, decomposed into trend, cycles, extra predictable variables, and fluctuations contributions, plus a single global residual.

Additional values are described in the APL/ApplyExtraMode reference.

Default is 'Forecasts and Error Bars'. When build_report=True, this parameter is overridden and 'First Forecast with Stable Components and Residues and Error Bars' is used automatically to supply all data required by the report.

Returns

DataFrame: Always contains the time column and ACTUAL (the observed value). Additional columns depend on prediction_type.

Examples

Case where there is no extra-predictable variable

>>> train_df = DataFrame(conn,
                         'SELECT "Date" , "Cash" '
                         'FROM APL_SAMPLES.CASHFLOWS_FULL '
                         'WHERE "Cash" is not null '
                         'ORDER BY 1')
>>> print(train_df.collect().tail(5))
           Date         Cash
246  2001-12-20  6382.441052
247  2001-12-21  5652.882539
248  2001-12-26  5081.372996
249  2001-12-27  5995.423295
250  2001-12-28  7111.416697

>>> model = AutoTimeSeries(conn, time_column_name='Date',
                           target='Cash',
                           horizon=3)
>>> model.fit(train_df)
>>> out = model.forecast(forecast_length=3)
>>> out.collect().tail(5)
           Date                        ACTUAL    PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
249  2001-12-27  5995.42329499999901392507553  6814.405390              NaN              NaN
250  2001-12-28  7111.41669699999907455205917  6839.334762              NaN              NaN
251  2001-12-29                          None  6864.371407      -224.079492     13952.822306
252  2001-12-30                          None  6889.515324      -211.264912     13990.295559
253  2001-12-31                          None  6914.766513      -187.180923     14016.713949

Case where there are extra-predictable variables

>>> train_df = DataFrame(conn,
                         'SELECT * '
                         'FROM APL_SAMPLES.CASHFLOWS_FULL '
                         'WHERE "Cash" IS NOT NULL '
                         'ORDER BY 1')
>>> print(train_df.collect().tail(5))
           Date  WorkingDaysIndices     ...       BeforeLastWMonth         Cash
246  2001-12-20                  13     ...                      1  6382.441052
247  2001-12-21                  14     ...                      1  5652.882539
248  2001-12-26                  15     ...                      0  5081.372996
249  2001-12-27                  16     ...                      0  5995.423295
250  2001-12-28                  17     ...                      0  7111.416697

>>> # Extra-predictable variables to be provided as the forecast period
>>> forecast_df = DataFrame(conn,
                            'SELECT * '
                            'FROM APL_SAMPLES.CASHFLOWS_FULL '
                            'WHERE "Cash" IS NULL '
                            'ORDER BY 1 '
                            'LIMIT 3')
>>> print(forecast_df.collect())
         Date  WorkingDaysIndices  ...   BeforeLastWMonth  Cash
0  2002-01-03                   0  ...                  0  None
1  2002-01-04                   1  ...                  0  None
2  2002-01-07                   2  ...                  0  None

>>> model = AutoTimeSeries(conn,
                           time_column_name='Date',
                           target='Cash',
                           horizon=3)
>>> model.fit(train_df)
>>> out = model.forecast(data=forecast_df)
>>> out.collect().tail(5)
           Date                          ACTUAL  PREDICTED  LOWER_INT_95PCT  UPPER_INT_95PCT
249  2001-12-27  5995.4232949999996101392507553    6814.41              NaN              NaN
250  2001-12-28  7111.4166969999996407455205917    6839.33              NaN              NaN
251  2001-12-29                            None    6864.37          -224.08         13952.82
252  2001-12-30                            None    6889.52          -211.26         13990.30
253  2001-12-31                            None    6914.77          -187.18         14016.71

get_model_components()¶

Return the description of the model components used to generate forecasts.

The components are trend, cycles, and fluctuations.

Returns

dict or pandas.DataFrame: If no segment column is given, a dictionary with 3 possible keys: 'Trend', 'Cycles', 'Fluctuations'. If a segment column is given, a pandas.DataFrame with the model components for each segment.

Examples

>>> model.get_model_components()
{
    "Trend": "Linear(TIME)",
    "Cycles": None,
    "Fluctuations": "AR(36)"
}

get_performance_metrics()¶

Return the performance metrics of the model.

The metrics are provided for each forecast horizon.

Returns

dict or pandas.DataFrame: If no segment column is given, a dictionary in which each metric is associated with a list containing <horizon> elements. If a segment column is given, a pandas.DataFrame with the metric values for each segment.

Examples

A model is trained with 4 horizons. The returned value will be:

>>> model.get_performance_metrics()
{
    'MAPE': [
        0.1529961017445385,
        0.1538823292343699,
        0.1564376267423695,
        0.15170398377407046
    ],
    ...
}

get_horizon_wide_metric(metric_name='MAPE')¶

Return the value of a performance metric averaged over the forecast horizon.

Parameters

metric_namestr, optional: Default value equals 'MAPE'. Possible values: 'MAPE', 'MPE', 'MeanAbsoluteError', 'RootMeanSquareError', 'SMAPE', 'L1', 'L2', 'P2', 'R2', 'U2'.

Returns

float or pandas.DataFrame: If no segment column is given, the average metric value on the forecast horizon. It is based on validation partition. If a segment column is given, a pandas.DataFrame with the average metric value on the forecast horizon for each segment.

load_model(schema_name, table_name, oid=None)¶

Load the model from a table.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID must be given as an identifier. If it is not provided, the whole table is read.

Notes

Before using a reloaded model for a new prediction, set the following parameters again: time_column_name, target. The SAP HANA ML library needs these parameters to prepare the dataset view. Otherwise, methods such as forecast() and predict() will fail.

Examples

>>> # Sets time_column_name and target again
>>> model = AutoTimeSeries(conn_context=conn, time_column_name='Date', target='Cash')
>>> model.load_model(schema_name='MY_SCHEMA', table_name='MY_MODEL_TABLE')
>>> model.predict(hana_df,
...               apply_horizon=(NB_HORIZON_TRAIN + 5),
...               apply_last_time_point=LAST_TRAIN_DATE)

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

build_report(segment_name=None, max_local_explanations=100)¶

Build and store the model HTML report.

This method only prepares and stores the report data internally. Call generate_html_report() or generate_notebook_iframe_report() afterwards to render or export it.

Parameters

segment_namestr, optional: If the model is segmented, the segment name for which the report will be built.
max_local_explanationsint, optional: The maximum number of local explanations displayed in the report. Default is 100.

generate_html_report(filename)¶

Save the model report as an HTML file.

Parameters

filenamestr: The name of the output HTML file (without the .html extension).

Raises

RuntimeError: If build_report() has not been called yet.

generate_notebook_iframe_report()¶

Render the model report as an iframe in a Jupyter notebook.

Raises

RuntimeError: If build_report() has not been called yet.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

hana_ml.algorithms.apl.classification¶

This module provides the legacy SAP HANA APL binary classification algorithm.

Warning

This module provides the legacy algorithm. Use hana_ml.algorithms.apl.gradient_boosting_classification instead for improved performance. For more information about the differences between Gradient Boosting models and Legacy models, see Gradient Boosting Versus Legacy Models.

The following classes are available:

AutoClassifier

class hana_ml.algorithms.apl.classification.AutoClassifier(conn_context=None, variable_auto_selection=True, polynomial_degree=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, variable_selection_best_iteration=None, variable_selection_min_nb_of_final_variables=None, variable_selection_max_nb_of_final_variables=None, variable_selection_mode=None, variable_selection_nb_variables_removed_by_step=None, variable_selection_percentage_of_contribution_kept_by_step=None, variable_selection_quality_bar=None, variable_selection_quality_criteria=None, target_key=None, cutting_strategy=None, exclude_low_predictive_confidence=None, score_bins_count=None, other_train_apl_aliases=None, **other_params)¶

Bases: RobustRegressionBase

Legacy SAP HANA APL Binary Classifier algorithm.

Warning

This is a legacy algorithm. Use GradientBoostingBinaryClassifier instead for improved performance. For more information about the differences between Gradient Boosting models and Legacy models, see Gradient Boosting Versus Legacy Models.

Parameters

conn_contextConnectionContext, optional: The connection object to an SAP HANA database. This parameter is not needed anymore. It will be set automatically when a dataset is used in fit() or predict().
variable_auto_selectionbool, optional: When set to True, variable auto-selection is activated. Variable auto-selection enables to maintain the performance of a model while keeping the lowest number of variables. Default is True.
polynomial_degreeint, optional: The polynomial degree of the model. Default is 1.
variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.
variable_value_typesdict, optional: Specifies the variable value type (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
extra_applyout_settingsdict, optional: Additional APL apply parameters controlling the model output. See Advanced Apply Settings for the available parameters. For example: {'APL/ApplyReasonCode': '3;Mean;Below;False'} adds reason codes explaining each prediction.
max_tasksint, optional: Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
variable_selection_best_iterationbool, optional: If True, uses the best intermediate model from the variable selection process (usually the penultimate iteration). If False, uses the last model. Default is True.
variable_selection_min_nb_of_final_variablesint, optional: Minimum number of variables to retain in the final model. Default is 1.
variable_selection_max_nb_of_final_variablesint, optional: Maximum number of variables to retain in the final model. -1 keeps all variables. Default is -1.
variable_selection_modestr, optional: Strategy for automatic variable selection. Accepted values: 'ContributionBased', 'VariableBased'. Default is 'ContributionBased'.
variable_selection_nb_variables_removed_by_stepint, optional: Number of variables removed per iteration when variable_selection_mode='VariableBased'. Default is 1.
variable_selection_percentage_of_contribution_kept_by_stepfloat, optional: Fraction of information to retain at each selection step. Default is 0.95.
variable_selection_quality_barfloat, optional: Maximum model quality degradation accepted per selection step. A higher value results in fewer retained variables. Default is 0.05.
variable_selection_quality_criteriastr, optional: Quality metric used during variable selection. Accepted values: 'KiKr', 'Ki', 'Kr', 'None'. Default is 'KiKr'.
target_keystr, optional: Value of the target variable to treat as the positive class for binary classification. Defaults to the least frequent category.
cutting_strategystr, optional: Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.
exclude_low_predictive_confidencestr, optional: Whether to exclude variables with low predictive confidence from the model. Accepted values: 'System' (decided automatically), 'Enabled', 'Disabled'. Default is 'System'.
score_bins_countint, optional: Number of bins used for score variables. Default is 20.
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, label, weight])	Fit the model.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_feature_importances`()	Return the feature importances (`MaximumSmartVariableContribution`).
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the last trained model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data)	Make predictions with the fitted model.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`score`(data)	Compute the accuracy score on the provided test dataset.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

It is highly recommended to use a dataset with a key provided in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a key, because the model will not expect it.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.classification import AutoClassifier
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = AutoClassifier(variable_auto_selection=True)
>>> model.fit(hana_df, label='class', key='id')

Making the predictions

>>> apply_out = model.predict(hana_df)
>>> print(apply_out.head(3).collect())
    id  TRUE_LABEL  PREDICTED  PROBABILITY
0   30           0          0     0.688153
1   63           0          0     0.677693
2   66           0          0     0.700221

Adding individual contributions to the output of predictions

>>> model.set_params(extra_applyout_settings={'APL/ApplyContribution': 'all'})
>>> apply_out = model.predict(hana_df)
>>> print(apply_out.head(3).collect())
    id  TRUE_LABEL  PREDICTED  PROBABILITY  contrib_age_rr_class ...
0   30           0          0     0.688153              0.043387 ...
1   63           0          0     0.677693              0.042608 ...
2   66           0          0     0.700221              0.020784 ...

Adding reason codes to the output of predictions

>>> model.set_params(extra_applyout_settings={'APL/ApplyReasonCode': '3;Mean;Below;False'})
>>> apply_out = model.predict(hana_df)
>>> print(apply_out.head(3).collect())
   id  TRUE_LABEL  PREDICTED  PROBABILITY RCN_B_Mean_1_rr_class ...
0  30           0          0     0.688153         education-num ...
1  63           0          0     0.677693         education-num ...
2  66           0          0     0.700221         education-num ...

Debriefing

>>> model.get_performance_metrics()
OrderedDict([('L1', 0.2522171212463023), ('L2', 0.32254434028379236), ...])

>>> model.get_feature_importances()
OrderedDict([('marital-status', 0.2172766583204266), ('capital-gain', 0.19521247617062215), ...])

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> from hana_ml.model_storage import ModelStorage
>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My classification model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Exporting the SQL apply code

>>> sql = model.export_apply_code(code_type='HANA',
...                               key='id',
...                               schema_name='APL_SAMPLES',
...                               table_name='CENSUS')

fit(data, key=None, features=None, label=None, weight=None)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. But this is not recommended. See notes below.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all non-ID and non-label columns will be used.
labelstr, optional: The name of the label column. Default is the last column.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

self: The fitted model instance.

Notes

It is highly recommended to use a dataset with a key in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a dataset with a key, because the model will not expect it.

predict(data)¶

Make predictions with the fitted model.

Special outputs such as reason codes can be added by specifying extra_applyout_settings in the model constructor or via set_params().

Parameters

dataDataFrame: The dataset used for prediction.

Returns

DataFrame

A DataFrame with the following columns:

<key column name> — the key column, if it was provided in the dataset.
TRUE_LABEL — the actual class label, when present in the dataset.
PREDICTED — the predicted label.
PROBABILITY — the probability that the predicted label is correct.
Any extra columns requested via extra_applyout_settings (e.g. reason codes, individual contributions).

score(data)¶

Compute the accuracy score on the provided test dataset.

Parameters

dataDataFrame: The test dataset used to compute the score. The labels must be provided in the dataset.

Returns

float or pandas.DataFrame: If no segment column is configured, returns the accuracy score as a float. If a segment column is configured, returns a pandas.DataFrame with the accuracy score for each segment.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_feature_importances()¶

Return the feature importances (MaximumSmartVariableContribution).

Returns

collections.OrderedDict or pandas.DataFrame: If no segment column is configured, an OrderedDict mapping {feature_name: importance_value}, sorted by descending importance. If a segment column is configured, a pandas.DataFrame with feature importances for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_performance_metrics()¶

Return the performance metrics of the last trained model.

Returns

collections.OrderedDict or pandas.DataFrame: If no segment column is configured, an OrderedDict mapping metric name to metric value. If a segment column is configured, a pandas.DataFrame with performance metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_params(**parameters)¶

Set attributes of the current model.

Implemented for compatibility with scikit-learn.

Parameters

**parametersdict: The attribute names and their values.

Returns

self: The current instance.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

hana_ml.algorithms.apl.regression¶

This module provides the legacy SAP HANA APL regression algorithm.

Warning

This module provides the legacy algorithm. Use hana_ml.algorithms.apl.gradient_boosting_regression instead for improved performance. For more information about the differences between Gradient Boosting models and Legacy models, see Gradient Boosting Versus Legacy Models.

The following classes are available:

AutoRegressor

class hana_ml.algorithms.apl.regression.AutoRegressor(conn_context=None, variable_auto_selection=True, polynomial_degree=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, variable_selection_best_iteration=None, variable_selection_min_nb_of_final_variables=None, variable_selection_max_nb_of_final_variables=None, variable_selection_mode=None, variable_selection_nb_variables_removed_by_step=None, variable_selection_percentage_of_contribution_kept_by_step=None, variable_selection_quality_bar=None, variable_selection_quality_criteria=None, cutting_strategy=None, exclude_low_predictive_confidence=None, score_bins_count=None, other_train_apl_aliases=None, **other_params)¶

Bases: RobustRegressionBase

Legacy SAP HANA APL regression algorithm.

Warning

This is a legacy algorithm. Use GradientBoostingRegressor instead for improved performance. For more information about the differences between Gradient Boosting models and Legacy models, see Gradient Boosting Versus Legacy Models.

Parameters

conn_contextConnectionContext, optional: The connection object to an SAP HANA database. This parameter is not needed anymore. It will be set automatically when a dataset is used in fit() or predict().
variable_auto_selectionbool, optional: When set to True, variable auto-selection is activated. Variable auto-selection enables to maintain the performance of a model while keeping the lowest number of variables. Default is True.
polynomial_degreeint, optional: The polynomial degree of the model. Default is 1.
variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.
variable_value_typesdict, optional: Specifies the variable value type (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
extra_applyout_settingsdict, optional: Additional APL apply parameters controlling the model output. See Advanced Apply Settings for the available parameters. For example: {'APL/ApplyReasonCode': '3;Mean;Below;False'} adds reason codes explaining each prediction.
max_tasksint, optional: Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
variable_selection_best_iterationbool, optional: If True, uses the best intermediate model from the variable selection process (usually the penultimate iteration). If False, uses the last model. Default is True.
variable_selection_min_nb_of_final_variablesint, optional: Minimum number of variables to retain in the final model. Default is 1.
variable_selection_max_nb_of_final_variablesint, optional: Maximum number of variables to retain in the final model. -1 keeps all variables. Default is -1.
variable_selection_modestr, optional: Strategy for automatic variable selection. Accepted values: 'ContributionBased', 'VariableBased'. Default is 'ContributionBased'.
variable_selection_nb_variables_removed_by_stepint, optional: Number of variables removed per iteration when variable_selection_mode='VariableBased'. Default is 1.
variable_selection_percentage_of_contribution_kept_by_stepfloat, optional: Fraction of information to retain at each selection step. Default is 0.95.
variable_selection_quality_barfloat, optional: Maximum model quality degradation accepted per selection step. A higher value results in fewer retained variables. Default is 0.05.
variable_selection_quality_criteriastr, optional: Quality metric used during variable selection. Accepted values: 'KiKr', 'Ki', 'Kr', 'None'. Default is 'KiKr'.
cutting_strategystr, optional: Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.
exclude_low_predictive_confidencestr, optional: Whether to exclude variables with low predictive confidence from the model. Accepted values: 'System' (decided automatically), 'Enabled', 'Disabled'. Default is 'System'.
score_bins_countint, optional: Number of bins used for score variables. Default is 20.
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, label, weight])	Fit the model.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_feature_importances`()	Return the feature importances (`MaximumSmartVariableContribution`).
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_performance_metrics`()	Return the performance metrics of the last trained model.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data)	Make predictions with the fitted model.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`score`(data)	Compute the R2 score (coefficient of determination) on the provided test dataset.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

It is highly recommended to use a dataset with a key provided in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a key, because the model will not expect it.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'age': 'number'
})
model.set_params(variable_value_types={
    'age': 'continuous'
})
model.set_params(variable_missing_strings={
    'age': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.regression import AutoRegressor
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA Database

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = AutoRegressor(variable_auto_selection=True)
>>> model.fit(hana_df, label='age', key='id', features=['workclass',
...                                                     'fnlwgt',
...                                                     'education',
...                                                     'education-num',
...                                                     'marital-status'])

Making a prediction

>>> applyout_df = model.predict(hana_df)
>>> print(applyout_df.head(5).collect())
          id  TRUE_LABEL  PREDICTED
0         30          49         42
1         63          48         42
2         66          36         42
3        110          42         42
4        335          53         42

Debriefing

>>> model.get_performance_metrics()
OrderedDict([('L1', 8.59885654599923), ('L2', 11.012352163260505), ...])

>>> model.get_feature_importances()
OrderedDict([('marital-status', 0.7916100739306074), ('education-num', 0.13524836400650087), ...])

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My regression model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Reloading the model and making another prediction

>>> model2 = AutoRegressor(conn_context=conn)
>>> model2.load_model(schema_name='MySchema', table_name='MyTable')

>>> applyout2 = model2.predict(hana_df)
>>> applyout2.head(5).collect()
          id  TRUE_LABEL  PREDICTED
0         30          49         42
1         63          48         42
2         66          36         42
3        110          42         42
4        335          53         42

Exporting the SQL apply code

>>> sql = model.export_apply_code(code_type='HANA',
...                               key='id',
...                               schema_name='APL_SAMPLES',
...                               table_name='CENSUS')

fit(data, key=None, features=None, label=None, weight=None)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. If key is not provided, an internal key is created. This is not recommended. See notes below.
featureslist of str, optional: Names of the feature columns. If features is not provided, all non-ID and non-label columns will be used.
labelstr, optional: The name of the label column. Default is the last column.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

self: The fitted model instance.

Notes

It is highly recommended to use a dataset with a key provided in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a dataset with a key, because the model will not expect it.

predict(data)¶

Make predictions with the fitted model.

Special outputs such as reason codes can be added by specifying extra_applyout_settings in the model constructor or via set_params().

Parameters

dataDataFrame: The dataset used for prediction.

Returns

DataFrame

A DataFrame with the following columns:

<key column name> — the key column, if it was provided in the dataset.
TRUE_LABEL — the actual value, when present in the dataset.
PREDICTED — the predicted value.
Any extra columns requested via extra_applyout_settings (e.g. reason codes, individual contributions).

score(data)¶

Compute the R2 score (coefficient of determination) on the provided test dataset.

Parameters

dataDataFrame: The test dataset used to compute the score. The labels must be provided in the dataset.

Returns

float or pandas.DataFrame: If no segment column is configured, returns the R2 score as a float. If a segment column is configured, returns a pandas.DataFrame with the R2 score for each segment.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_feature_importances()¶

Return the feature importances (MaximumSmartVariableContribution).

Returns

collections.OrderedDict or pandas.DataFrame: If no segment column is configured, an OrderedDict mapping {feature_name: importance_value}, sorted by descending importance. If a segment column is configured, a pandas.DataFrame with feature importances for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_performance_metrics()¶

Return the performance metrics of the last trained model.

Returns

collections.OrderedDict or pandas.DataFrame: If no segment column is configured, an OrderedDict mapping metric name to metric value. If a segment column is configured, a pandas.DataFrame with performance metrics for each segment.

Raises

FitIncompleteError: If fit() has not been called yet.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_params(**parameters)¶

Set attributes of the current model.

Implemented for compatibility with scikit-learn.

Parameters

**parametersdict: The attribute names and their values.

Returns

self: The current instance.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

hana_ml.algorithms.apl.clustering¶

This module provides the SAP HANA APL clustering algorithms.

The following classes are available:

AutoUnsupervisedClustering

AutoSupervisedClustering

class hana_ml.algorithms.apl.clustering.AutoUnsupervisedClustering(conn_context=None, nb_clusters=None, nb_clusters_min=None, nb_clusters_max=None, distance=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, calculate_cross_statistics=None, calculate_sql_expressions=None, cutting_strategy=None, encoding_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: _AutoClusteringBase

SAP HANA APL unsupervised clustering algorithm.

Parameters

nb_clustersint, optional: The number of clusters to create. Default is 10.
nb_clusters_minint, optional: The minimum number of clusters to create. If nb_clusters is set, this parameter is ignored.
nb_clusters_maxint, optional: The maximum number of clusters to create. If nb_clusters is set, this parameter is ignored.
distancestr, optional: The metric used to measure the distance between data points. The possible values are: 'L1', 'L2', 'LInf', 'SystemDetermined'. Default is 'SystemDetermined'.
variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.
variable_value_typesdict, optional: Specifies the variable value types (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
extra_applyout_settingsdict, optional: Defines the output to generate when applying the model. See documentation on predict() method for more information.
max_tasksint, optional: Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
calculate_cross_statisticsstr, optional: Whether to compute cross statistics between cluster IDs and input variables. Accepted values: 'enabled', 'disabled'. Default is 'enabled'.
calculate_sql_expressionsbool, optional: If True, generates SQL expressions for the clustering model. Default is False.
cutting_strategystr, optional: Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.
encoding_strategystr, optional: Type of encoding applied to input variables before clustering. Accepted values: 'Uniform', 'Unsupervised', 'TargetMean', 'Natural', 'SystemDetermined', 'MinMax', 'MinMaxCentered', 'StdDevNormalization'. Default is 'Unsupervised'.
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, features, weight])	Fit the model.
`fit_predict`(data[, key, features, weight])	Fit a clustering model and apply it to the training dataset.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_metrics`()	Return metrics about the model.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`predict`(data)	Predict which cluster each row belongs to.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

The algorithm may detect fewer clusters than requested. This happens when a cluster detected on the estimation dataset was not found on the validation dataset. In that case, this cluster will be considered unstable and will be removed from the model. Users can get the number of clusters actually found in the INDICATORS table. For example:

# The actual number of clusters found
d = model_u.get_indicators().collect()
d[d.KEY=='FinalClusterCount'][['KEY','VALUE']]

It is highly recommended to use a dataset with a key provided in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a key, because the model will not expect it.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.clustering import AutoUnsupervisedClustering
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = AutoUnsupervisedClustering(conn, nb_clusters=5)
>>> model.fit(data=hana_df, key='id')

Debriefing

>>> model.get_metrics()
OrderedDict([('SimplifiedSilhouette', 0.3448029020802121), ('RSS', 4675.706587754118), ...])

>>> model.get_metrics_by_cluster()
{
    'Frequency': {
        1: 0.23053242076908276,
        2: 0.27434649954646656,
        3: 0.09628652318517908,
        4: 0.29919463456199663,
        5: 0.09963992193727494
    },
    'IntraInertia': {
        1: 0.6734978174937322,
        2: 0.7202839995396123,
        3: 0.5516800856975772,
        4: 0.6969632183111357,
        5: 0.5809322138167139
    },
    'RSS': {
        1: 5648.626195319932,
        2: 7189.15459940487,
        3: 1932.5353401986129,
        4: 7586.444631316713,
        5: 2105.879275085588
    },
    'SimplifiedSilhouette': {
        1: 0.1383827622819234,
        2: 0.14716862328457128,
        3: 0.18753797605134545,
        4: 0.13679980173383793,
        5: 0.15481377834381388
    },
    'KL': {
        1: OrderedDict(
            [
                ('relationship', 0.4951910610641741),
                ('marital-status', 0.2776259711735807),
                ('hours-per-week', 0.20990189265572687),
                ('education-num', 0.1996353893520096),
                ('education', 0.19963538935200956),
                ...
            ]
        ),
        ...
    }
}

Predicting which cluster a data point belongs to

>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  CLOSEST_CLUSTER_1  DISTANCE_TO_CLOSEST_CENTROID_1
0   30                  3                        0.640378
1   63                  4                        0.611050
2   66                  3                        0.640378
3  110                  4                        0.611050
4  335                  1                        0.851054

Determining the 2 closest clusters

>>> model.set_params(extra_applyout_settings={'mode': 'closest_distances', 'nb_distances': 2})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  CLOSEST_CLUSTER_1  ...  CLOSEST_CLUSTER_2  DISTANCE_TO_CLOSEST_CENTROID_2
0   30                  3  ...                  4                        0.730330
1   63                  4  ...                  1                        0.851054
2   66                  3  ...                  4                        0.730330
3  110                  4  ...                  1                        0.851054
4  335                  1  ...                  4                        0.906003

Retrieving the distances to all clusters

>>> model.set_params(extra_applyout_settings={'mode': 'all_distances'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  DISTANCE_TO_CENTROID_1  ...  DISTANCE_TO_CENTROID_5
0   30                       3  ...                1.160697
1   63                       4  ...                1.160697
2   66                       3  ...                1.160697

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My model name'
>>> model_storage.save_model(model=model)

Reloading the model for further use

>>> model2 = AutoUnsupervisedClustering(conn_context=conn)
>>> model2.load_model(schema_name='MySchema', table_name='MyTable')
>>> applyout2 = model2.predict(hana_df)
>>> applyout2.head(3).collect()
    id  CLOSEST_CLUSTER_1  DISTANCE_TO_CLOSEST_CENTROID_1
0   30                  3                        0.640378
1   63                  4                        0.611050
2   66                  3                        0.640378

Exporting the SQL apply code

>>> model = AutoUnsupervisedClustering(conn, nb_clusters=5,
...                                    calculate_sql_expressions='enabled')
>>> model.fit(data=hana_df, key='id')
>>> sql = model.export_apply_code(code_type='HANA',
...                               key='id',
...                               schema_name='APL_SAMPLES',
...                               table_name='CENSUS')

fit(data, key=None, features=None, weight=None)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. But this is not recommended.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all columns except the ID column will be used.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

self: The fitted model instance.

fit_predict(data, key=None, features=None, weight=None)¶

Fit a clustering model and apply it to the training dataset.

Parameters

dataDataFrame: The input dataset.
keystr, optional: The name of the ID column.
featureslist of str, optional: The names of the feature columns. If features is not provided, all non-ID columns will be used.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

DataFrame: The output is the same as the predict() method.

Notes

See the predict() method for how to control the output format using set_params().

get_metrics()¶

Return metrics about the model.

Returns

dict or pandas.DataFrame: If no segment column is given, a dictionary object containing a set of clustering metrics and their values. If a segment column is given, a pandas.DataFrame with the metrics for each segment.

Examples

>>> model.get_metrics()
{
    'SimplifiedSilhouette': 0.14668968897882997,
    'RSS': 24462.640041325714,
    'IntraInertia': 3.2233573348587714,
    'KL': {
        1: OrderedDict([
            ('hours-per-week', 0.2971627592049324),
            ('occupation', 0.11944355994892383),
            ('relationship', 0.06772624975990414),
            ('education-num', 0.06377345492340795),
            ('education', 0.06377345492340793),
            ...
        ]),
        ...
    }
}

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

predict(data)¶

Predict which cluster each row belongs to.

Parameters

dataDataFrame: The dataset for which to generate cluster predictions. Must have the same structure as the one used in fit().

Returns

DataFrame

By default, the ID of the closest cluster and the distance to its centroid are provided. Different outputs can be requested by setting extra_applyout_settings on the model (in the constructor or via set_params()). That parameter is a dictionary with 'mode' and 'nb_distances' as keys.

If mode is 'closest_distances', cluster IDs and distances to centroids are provided from closest to furthest. Output columns:

<key column>,
CLOSEST_CLUSTER_1,
DISTANCE_TO_CLOSEST_CENTROID_1,
CLOSEST_CLUSTER_2,
DISTANCE_TO_CLOSEST_CENTROID_2,
...

If mode is 'all_distances', distances to all cluster centroids are provided in cluster ID order. Output columns:

<key column>,
DISTANCE_TO_CENTROID_1,
DISTANCE_TO_CENTROID_2,
...

nb_distances limits the output to the closest clusters. Only valid when mode is 'closest_distances'; ignored otherwise. Can be set to 'all' or a positive integer.

Examples

Retrieving the IDs of the 3 closest clusters and the distances to their centroids

>>> model.set_params(extra_applyout_settings={'mode': 'closest_distances', 'nb_distances': '3'})
>>> out = model.predict(hana_df)
>>> out.head(3).collect()
    id  CLOSEST_CLUSTER_1  ...  CLOSEST_CLUSTER_3  DISTANCE_TO_CLOSEST_CENTROID_3
0   30                  3  ...                  4                        0.730330
1   63                  4  ...                  1                        0.851054
2   66                  3  ...                  4                        0.730330

Retrieving the distances to all clusters

>>> model.set_params(extra_applyout_settings={'mode': 'all_distances'})
>>> out = model.predict(hana_df)
>>> out.head(3).collect()
   id  DISTANCE_TO_CENTROID_1  DISTANCE_TO_CENTROID_2  ...  DISTANCE_TO_CENTROID_5
0  30                0.994595                0.877414  ...                0.782949
1  63                0.994595                0.985202  ...                0.782949
2  66                0.994595                0.877414  ...                0.782949

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: The set of parameters with their new values.

Returns

self: The updated model instance.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

class hana_ml.algorithms.apl.clustering.AutoSupervisedClustering(conn_context=None, label=None, nb_clusters=None, nb_clusters_min=None, nb_clusters_max=None, distance=None, variable_storages=None, variable_value_types=None, variable_missing_strings=None, extra_applyout_settings=None, max_tasks=None, segment_column_name=None, calculate_cross_statistics=None, calculate_sql_expressions=None, cutting_strategy=None, encoding_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: _AutoClusteringBase

SAP HANA APL supervised clustering algorithm.

Clusters are determined with respect to a label variable.

Parameters

labelstr, optional: The name of the label column. Can also be set later via set_params() or passed to fit().
nb_clustersint, optional: The number of clusters to create. Default is 10.
nb_clusters_minint, optional: The minimum number of clusters to create. If nb_clusters is set, this parameter is ignored.
nb_clusters_maxint, optional: The maximum number of clusters to create. If nb_clusters is set, this parameter is ignored.
distancestr, optional: The metric used to measure the distance between data points. The possible values are: 'L1', 'L2', 'LInf', 'SystemDetermined'. Default is 'SystemDetermined'.
variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}. See notes below for more details.
variable_value_typesdict, optional: Specifies the variable value types (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}. See notes below for more details.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
extra_applyout_settingsdict, optional: Defines the output to generate when applying the model. See documentation on predict() method for more information.
max_tasksint, optional: Maximum number of parallel tasks during training and prediction. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
calculate_cross_statisticsstr, optional: Whether to compute cross statistics between cluster IDs and input variables. Accepted values: 'enabled', 'disabled'. Default is 'enabled'.
calculate_sql_expressionsbool, optional: If True, generates SQL expressions for the clustering model. Default is False.
cutting_strategystr, optional: Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.
encoding_strategystr, optional: Type of encoding applied to input variables before clustering. Accepted values: 'Uniform', 'Unsupervised', 'TargetMean', 'Natural', 'SystemDetermined', 'MinMax', 'MinMaxCentered', 'StdDevNormalization'. Default is 'TargetMean'.
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Attributes

model_DataFrame: The trained model content.
summary_DataFrame: The model training summary table.
indicators_DataFrame: Various metrics related to the model and its variables.
fit_operation_log_DataFrame: The operation log produced during model training.
var_desc_DataFrame: The variable description table built during model training.
applyout_DataFrame: The predictions generated the last time the model was applied.
predict_operation_log_DataFrame: The operation log produced during prediction.

Methods

`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(data[, key, label, features, weight])	Fit the model.
`fit_predict`(data[, key, label, features, weight])	Fit a clustering model and apply it to the training dataset.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_metrics`()	Return metrics about the model.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Load the model from a table.
`predict`(data)	Assign each row to the closest cluster.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

The algorithm may detect fewer clusters than requested. This happens when a cluster detected on the estimation dataset was not found on the validation dataset. In that case, this cluster will be considered unstable and will be removed from the model. Users can get the number of clusters actually found in the INDICATORS table. For example:

# The actual number of clusters found
d = model_u.get_indicators().collect()
d[d.KEY=='FinalClusterCount'][['KEY','VALUE']]

It is highly recommended to use a dataset with a key provided in the fit() method. If not, once the model is trained, it will not be possible anymore to use the predict() method with a key, because the model will not expect it.

By default, when variable_storages, variable_value_types, and variable_missing_strings are not provided, SAP HANA APL guesses the variable description by reading the first 100 rows. This does not always produce the correct result. These parameters can be used to override the default guess. For example:

model.set_params(variable_storages={
    'ID': 'integer',
    'sepal length (cm)': 'number'
})
model.set_params(variable_value_types={
    'sepal length (cm)': 'continuous'
})
model.set_params(variable_missing_strings={
    'sepal length (cm)': '-1'
})

Examples

>>> from hana_ml.algorithms.apl.clustering import AutoSupervisedClustering
>>> from hana_ml.dataframe import ConnectionContext, DataFrame

Connecting to SAP HANA

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> hana_df = DataFrame(conn, 'SELECT * FROM APL_SAMPLES.CENSUS')

Creating and fitting the model

>>> model = AutoSupervisedClustering(nb_clusters=5)
>>> model.fit(data=hana_df, key='id', label='class')

Debriefing

>>> model.get_metrics()
OrderedDict([('SimplifiedSilhouette', 0.3448029020802121), ('RSS', 4675.706587754118), ...])

Predicting which cluster a data point belongs to

>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  CLOSEST_CLUSTER_1  DISTANCE_TO_CLOSEST_CENTROID_1
0   30                  3                        0.640378
1   63                  4                        0.611050
2   66                  3                        0.640378
3  110                  4                        0.611050
4  335                  1                        0.851054

Determining the 2 closest clusters

>>> model.set_params(extra_applyout_settings={'mode':'closest_distances', 'nb_distances': 2})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  CLOSEST_CLUSTER_1  ...  CLOSEST_CLUSTER_2  DISTANCE_TO_CLOSEST_CENTROID_2
0   30                  3  ...                  4                        0.730330
1   63                  4  ...                  1                        0.851054
2   66                  3  ...                  4                        0.730330
3  110                  4  ...                  1                        0.851054
4  335                  1  ...                  4                        0.906003

Retrieving the distances to all clusters

>>> model.set_params(extra_applyout_settings={'mode': 'all_distances'})
>>> applyout_df = model.predict(hana_df)
>>> applyout_df.collect() # returns the output as a pandas DataFrame
    id  DISTANCE_TO_CENTROID_1  ...  DISTANCE_TO_CENTROID_5
0   30                0.851054  ...                1.160697
1   63                0.751054  ...                1.160697
2   66                0.906003  ...                1.160697

Saving the model in the schema named 'MODEL_STORAGE' (see ModelStorage for further options)

>>> model_storage = ModelStorage(connection_context=conn, schema='MODEL_STORAGE')
>>> model.name = 'My model name'
>>> model_storage.save_model(model=model, if_exists='replace')

Reloading the model for further use

Note that the label must be specified again before calling predict().

>>> model2 = AutoSupervisedClustering()
>>> model2.set_params(label='class')
>>> model2.load_model(schema_name='MySchema', table_name='MyTable')
>>> applyout2 = model2.predict(hana_df)
>>> applyout2.head(3).collect()
    id  CLOSEST_CLUSTER_1  DISTANCE_TO_CLOSEST_CENTROID_1
0   30                  3                        0.640378
1   63                  4                        0.611050
2   66                  3                        0.640378

Exporting the SQL apply code

>>> model = AutoSupervisedClustering(conn, nb_clusters=5,
                                     calculate_sql_expressions='enabled')
>>> model.fit(data=hana_df, key='id', label='class')
>>> sql = model.export_apply_code(code_type='HANA',
                                  key='id',
                                  schema_name='APL_SAMPLES',
                                  table_name='CENSUS')

set_params(**parameters)¶

Set attributes of the current model.

Parameters

**parametersdict: Attribute names and values.

Returns

self: The updated model instance.

fit(data, key=None, label=None, features=None, weight=None)¶

Fit the model.

Parameters

dataDataFrame: The training dataset.
keystr, optional: The name of the ID column. This column will not be used as a feature in the model. It is returned as the row identifier in prediction results. If key is not provided, an internal key is created. But this is not recommended.
labelstr, optional: The name of the label column. If not given, the model label attribute will be used. If neither is defined, an error will be raised.
featureslist of str, optional: The names of the features to be used in the model. If features is not provided, all columns except the ID and label columns will be used.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

self: The fitted model instance.

Raises

TypeError: If label is not provided here and was not set via label either.

predict(data)¶

Assign each row to the closest cluster.

Parameters

dataDataFrame: The dataset for which to generate cluster predictions. Must have the same structure as the data used in fit().

Returns

DataFrame

By default, the ID of the closest cluster and the distance to its centroid are provided. The output can be customized using the extra_applyout_settings parameter (set in the constructor or via set_params()).

extra_applyout_settings is a dict with 'mode' and 'nb_distances' as keys.

If 'mode' is 'closest_distances', cluster IDs and distances to centroids are provided from the closest to the furthest cluster. The output columns are:

<key column name>
CLOSEST_CLUSTER_1
DISTANCE_TO_CLOSEST_CENTROID_1
CLOSEST_CLUSTER_2
DISTANCE_TO_CLOSEST_CENTROID_2
...

If 'mode' is 'all_distances', the distances to the centroids of all clusters are provided in cluster ID order. The output columns are:

<key column name>
DISTANCE_TO_CENTROID_1
DISTANCE_TO_CENTROID_2
...

'nb_distances' limits the output to the closest clusters. It is only valid when 'mode' is 'closest_distances' (ignored when 'mode' is 'all_distances'). It can be set to 'all' or a positive integer.

Examples

Retrieving the IDs of the 3 closest clusters and the distances to their centroids

>>> extra_applyout_settings = {'mode': 'closest_distances', 'nb_distances': 3}
>>> model.set_params(extra_applyout_settings=extra_applyout_settings)
>>> out = model.predict(hana_df)
>>> out.head(3).collect()
    id  CLOSEST_CLUSTER_1  ...  CLOSEST_CLUSTER_3  DISTANCE_TO_CLOSEST_CENTROID_3
0   30                  3  ...                  4                        0.730330
1   63                  4  ...                  1                        0.851054
2   66                  3  ...                  4                        0.730330

Retrieving the distances to all clusters

>>> model.set_params(extra_applyout_settings={'mode': 'all_distances'})
>>> out = model.predict(hana_df)
>>> out.head(3).collect()
   id  DISTANCE_TO_CENTROID_1  DISTANCE_TO_CENTROID_2  ...  DISTANCE_TO_CENTROID_5
0  30                0.994595                0.877414  ...                0.782949
1  63                0.994595                0.985202  ...                0.782949
2  66                0.994595                0.877414  ...                0.782949

fit_predict(data, key=None, label=None, features=None, weight=None)¶

Fit a clustering model and apply it to the training dataset.

Parameters

dataDataFrame: The input dataset.
keystr, optional: The name of the ID column.
labelstr, optional: The name of the label column.
featureslist of str, optional: The names of the feature columns. If features is not provided, all non-ID and non-label columns will be used.
weightstr, optional: The name of the weight column. Allows assigning a relative weight to each observation.

Returns

DataFrame: The output is the same as the predict() method.

Notes

See the predict() method for how to control the output format using set_params().

get_metrics()¶

Return metrics about the model.

Returns

dict or pandas.DataFrame: If no segment column is given, a dictionary object containing a set of clustering metrics and their values. If a segment column is given, a pandas.DataFrame with the metrics for each segment.

Examples

>>> model.get_metrics()
{
    'SimplifiedSilhouette': 0.14668968897882997,
    'RSS': 24462.640041325714,
    'IntraInertia': 3.2233573348587714,
    'Frequency': {
        1: 0.3167862345729914,
        2: 0.35590005772243755,
        3: 0.3273137077045711
    },
    'IntraInertia': {
        1: 0.7450335510518645,
        2: 0.708350629565789,
        3: 0.7006679558645009
    },
    'RSS': {
        1: 8586.511675872738,
        2: 9171.723951617836,
        3: 8343.554018434477
    },
    'SimplifiedSilhouette': {
        1: 0.13324659043317924,
        2: 0.14182734764281074,
        3: 0.1311620470933516
    },
    'TargetMean': {
        1: 0.1744734931009441,
        2: 0.022912917070469333,
        3: 0.3895408163265306
    },
    'TargetStandardDeviation': {
        1: 0.37951613049526484,
        2: 0.14962591788119842,
        3: 0.48764615116105525
    },
    'KL': {
        1: OrderedDict([
            ('hours-per-week', 0.2971627592049324),
            ('occupation', 0.11944355994892383),
            ('relationship', 0.06772624975990414),
            ('education-num', 0.06377345492340795),
            ('education', 0.06377345492340793),
            ...
        ]),
        ...
    }
}

load_model(schema_name, table_name, oid=None)¶

Load the model from a table.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID must be given as an identifier. If not provided, the whole table is read.

Notes

Before using a reloaded model for a new prediction, label must be re-specified. Otherwise, the predict() method will fail.

Examples

>>> model = AutoSupervisedClustering(label='class')
>>> model.load_model(schema_name='MY_SCHEMA', table_name='MY_MODEL_TABLE')
>>> model.predict(hana_df)

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.

hana_ml.algorithms.apl.drift_detector¶

This module provides the DriftDetector class for detecting data drift between a reference dataset and new data.

class hana_ml.algorithms.apl.drift_detector.DriftDetector(variable_storages=None, variable_value_types=None, variable_missing_strings=None, max_tasks=None, segment_column_name=None, cutting_strategy=None, other_train_apl_aliases=None, **other_params)¶

Bases: APLBase

A class to detect data drift between a reference dataset and new data.

Data drift refers to changes in the statistical properties of the data over time, which can affect the performance of machine learning models.

Parameters

variable_storagesdict, optional: Specifies the variable data types (string, integer, number). For example, {'VAR1': 'string', 'VAR2': 'number'}.
variable_value_typesdict, optional: Specifies the variable value types (continuous, nominal, ordinal). For example, {'VAR1': 'continuous', 'VAR2': 'nominal'}.
variable_missing_stringsdict, optional: Specifies the variable values that will be taken as missing. For example, {'VAR1': '???'} means anytime the variable value equals '???', it will be taken as missing.
max_tasksint, optional: Maximum number of parallel tasks during training and detection. 0 uses all available HANA threads; 1 disables parallelization. Default is 1.
segment_column_namestr, optional: Name of the column containing the segment key, enabling one-model-per-segment training.
cutting_strategystr, optional: Strategy for splitting the training dataset into estimation, validation, and test subsets. Accepted values: 'random', 'periodic', 'sequential', 'random with no test', 'periodic with no test', 'sequential with no test', 'random with test at end', 'periodic with test at end'. Default is 'random with no test'. For a full description of all strategies, see Partition Strategies.
other_train_apl_aliasesdict, optional: Additional APL training aliases as a {'APL/AliasName': value} dict. Unlike the named parameters above, any alias accepted by APL can be used here with no validation in Python. See Common APL Aliases for Model Training in the SAP HANA APL documentation.

Methods

`build_report`([threshold, segment_name])	Build a comprehensive data drift report.
`detect`(new_data[, threshold, build_report])	Detect drift in the provided data.
`disable_hana_execution`()	Disable HANA execution so that only SQL script is generated.
`enable_hana_execution`()	Re-enable HANA execution after it was disabled by `disable_hana_execution()`.
`export_apply_code`(code_type[, key, label, ...])	Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.
`fit`(reference_data[, features, label, weight])	Fit the drift detector using the provided reference data.
`fit_detect`(reference_data, new_data[, ...])	Detect drift between reference data and new data.
`generate_html_report`(filename)	Generate an HTML report and save it to the specified file.
`generate_notebook_iframe_report`()	Generate a notebook iframe report for a Jupyter notebook.
`get_apl_version`()	Get version and configuration information about the SAP HANA APL installation.
`get_artifacts_recorder`()	Return the SQL artifacts recorder used for design-time artifact generation.
`get_debrief_report`(report_name, **params)	Retrieve a standard statistical report.
`get_detect_operation_log`()	Return the operation log table from the detect operation.
`get_fit_operation_log`()	Retrieve the operation log produced during model training.
`get_indicators`()	Retrieve the indicators table produced during model training.
`get_model_info`()	Get information about an existing model.
`get_params`()	Retrieve the current model attributes as a dictionary.
`get_predict_operation_log`()	Retrieve the operation log produced during prediction.
`get_summary`()	Retrieve the summary table produced during model training.
`is_fitted`()	Checks if the model can be saved.
`load_model`(schema_name, table_name[, oid])	Loads the model from a table.
`save_artifact`(artifact_df, schema_name, ...)	Save an artifact (a temporary table) into a permanent table.
`save_model`(schema_name, table_name[, ...])	Save the model into a HANA table.
`schedule_fit`(output_table_name_model, ...)	Create a HANA scheduler job for model fitting.
`schedule_predict`(input_table_name_model, ...)	Create a HANA scheduler job for model prediction.
`set_params`(**parameters)	Set attributes of the current model.
`set_scale_out`([route_to, no_route_to, ...])	Specify hints for a scale-out environment.

Notes

When calling the fit_detect() method, the model is generated on-the-fly but is not returned. If a model must be saved, please consider using the fit() method instead.

Examples

>>> from hana_ml.dataframe import ConnectionContext, DataFrame
>>> from hana_ml.algorithms.apl.drift_detector import DriftDetector

Connecting to SAP HANA Database

>>> conn = ConnectionContext(HDB_HOST, HDB_PORT, HDB_USER, HDB_PASS)
>>> reference_data = DataFrame(conn, 'SELECT * FROM REFERENCE_DATA_TABLE')
>>> new_data = DataFrame(conn, 'SELECT * FROM NEW_DATA_TABLE')

Creating and fitting the detector

>>> drift_detector = DriftDetector()
>>> drift_detector.fit(reference_data, label='target')

Detecting drift in new data

>>> results = drift_detector.detect(new_data, threshold=0.9, build_report=True)
>>> print(results.collect())

Fitting and detecting drift in one step

>>> results = drift_detector.fit_detect(reference_data, new_data, label='target', threshold=0.9, build_report=True)
>>> print(results.collect())

Generating an HTML report

>>> drift_detector.generate_html_report('drift_report')

Generating a notebook iframe report

>>> drift_detector.generate_notebook_iframe_report()

fit(reference_data, features=None, label=None, weight=None)¶

Fit the drift detector using the provided reference data.

Parameters

reference_dataDataFrame: The reference dataset used to fit the drift detector.
featureslist of str, optional: The list of feature column names to be used for drift detection.
labelstr, optional: The name of the label column.
weightstr, optional: The name of the weight column.

Returns

self: The fitted drift detector.

detect(new_data, threshold=None, build_report=False)¶

Detect drift in the provided data.

Parameters

new_dataDataFrame: The dataset to compare against the reference dataset.
thresholdfloat, optional: The deviation indicator threshold for drift detection. Variables whose deviation indicator exceeds this value are flagged as drifted. The deviation indicator ranges from 0.0 (no drift) to 1.0 (maximum drift). Default is 0.95.
build_reportbool, optional: If True, a detailed report of the drift detection will be built. Default is False.

Returns

resultsDataFrame: A DataFrame containing the variables and their deviation indicators, sorted by the deviation indicator in descending order.

fit_detect(reference_data, new_data, features=None, label=None, weight=None, threshold=None, build_report=False)¶

Detect drift between reference data and new data.

When calling the fit_detect() method, the model is generated on-the-fly but is not returned. If a model must be saved, please consider using the fit() method instead.

Parameters

reference_dataDataFrame: The reference dataset.
new_dataDataFrame: The dataset to compare against the reference dataset.
featureslist of str, optional: The feature columns to consider for drift detection.
labelstr, optional: The label column in the datasets.
weightstr, optional: The weight column in the datasets.
thresholdfloat, optional: The deviation indicator threshold for drift detection. Variables whose deviation indicator exceeds this value are flagged as drifted. The deviation indicator ranges from 0.0 (no drift) to 1.0 (maximum drift). Default is 0.95.
build_reportbool, optional: If True, a detailed report of the drift detection will be built. Default is False.

Returns

resultsDataFrame: A DataFrame containing the variables and their deviation indicators, sorted by the deviation indicator in descending order.

build_report(threshold=None, segment_name=None)¶

Build a comprehensive data drift report.

This method generates a report that includes various types of data drift analyses:

Variable Drift
Category Drift
Category Frequencies
Target-Based Category Drift
Group Drift
Group Frequencies
Target-Based Group Drift

Each section of the report is built based on the data collected from the debrief reports. Sections are only included when the corresponding data is non-empty.

Use generate_html_report() to generate an HTML file for the report, or generate_notebook_iframe_report() to display the report in a Jupyter notebook.

Parameters

thresholdfloat, optional: The deviation indicator threshold for drift detection. Variables whose deviation indicator exceeds this value are flagged as drifted. The deviation indicator ranges from 0.0 (no drift) to 1.0 (maximum drift). Default is 0.95.
segment_namestr, optional: If the model is segmented, the segment name for which the report will be built.

generate_html_report(filename)¶

Generate an HTML report and save it to the specified file.

It requires that the build_report() method has been called beforehand to initialize the report builder.

Parameters

filenamestr: The name of the file where the HTML report will be saved.

generate_notebook_iframe_report()¶

Generate a notebook iframe report for a Jupyter notebook.

It requires that the build_report() method has been called beforehand to initialize the report builder.

get_detect_operation_log()¶

Return the operation log table from the detect operation.

Returns

DataFrame: The operation log table.

disable_hana_execution()¶

Disable HANA execution so that only SQL script is generated.

After calling this method, calls to fit() or predict() will generate and record SQL artifacts without executing them on HANA. Useful for design-time artifact generation workflows.

enable_hana_execution()¶

Re-enable HANA execution after it was disabled by disable_hana_execution().

After calling this method, calls to fit() or predict() will execute normally on HANA.

export_apply_code(code_type, key=None, label=None, schema_name=None, table_name=None, other_params=None)¶

Export code (SQL, JSON, etc.) to apply a trained model outside SAP HANA APL.

The exported code encodes the model's scoring logic in a self-contained format so that predictions can be made independently of SAP HANA APL.

Parameters

code_typestr

The format of the exported code.

'HANA' (SAP HANA SQL).
'JSON' (the only format supported for Gradient Boosting models).

Other supported formats are described in the EXPORT_APPLY_CODE reference.

keystr, optional

The name of the primary key column.

labelstr, optional

The name of the target column. Used only when the model has multiple targets. When omitted, code is generated for all targets.

schema_namestr, optional

The schema of the input table.

table_namestr, optional

The name of the input table.

other_paramsdict, optional

Additional APL configuration entries passed as {key: value} pairs. The full list of supported entries is available in the EXPORT_APPLY_CODE reference.

Returns

str or pandas.DataFrame: If no segment column is given, the exported code as a string. If a segment column is given, a pandas.DataFrame containing the exported code for each segment.

Raises

FitIncompleteError: If the model has not been fitted yet.

Examples

Exporting a model in JSON format (available for Gradient Boosting and Legacy Classification/Regression models)

>>> json_export = model.export_apply_code('JSON')

APL provides a JavaScript runtime in which you can make predictions based on any model that has been exported in JSON format. See JavaScript Runtime in the SAP HANA APL documentation.

Exporting SQL apply code (available for Clustering and Legacy Classification/Regression models)

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS')

Exporting SQL apply code with probability output

>>> sql = model.export_apply_code(
...     code_type='HANA',
...     key='id',
...     schema_name='APL_SAMPLES',
...     table_name='CENSUS',
...     other_params={'APL/ApplyExtraMode': 'Advanced Apply Settings',
...                   'APL/ApplyProba': 'true'})

get_apl_version()¶

Get version and configuration information about the SAP HANA APL installation.

Returns

pandas.DataFrame: Detailed information about the current APL version.

Raises

RuntimeError: If the call fails, either because SAP HANA APL is not installed or the current user does not have the appropriate rights.

get_artifacts_recorder()¶

Return the SQL artifacts recorder used for design-time artifact generation.

Returns

AplSqlArtifactsRecorder or None: The recorder instance, or None if no fit() or predict() has been called yet.

get_debrief_report(report_name, **params)¶

Retrieve a standard statistical report.

See Statistical Reports in the SAP HANA APL Developer Guide.

Parameters

report_namestr: The name of the statistical report to retrieve.
**paramsdict: Additional parameters to be passed to the report query.

Returns

DataFrame: The statistical report result.

get_fit_operation_log()¶

Retrieve the operation log produced during model training.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last fit() call.

Raises

FitIncompleteError: If fit() has not been called yet.

get_indicators()¶

Retrieve the indicators table produced during model training.

Returns

DataFrame: Reference to the INDICATORS table containing performance metrics of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

get_model_info()¶

Get information about an existing model.

Especially useful when a trained model was saved and reloaded. After calling this method, the model can provide summary and metrics as they were after the last fit.

Returns

list of DataFrame

DataFrames corresponding to the following tables:

Summary table
Variable roles table
Variable description table
Indicators table
Profit curves table

Raises

FitIncompleteError: If the model has not been fitted yet.

get_params()¶

Retrieve the current model attributes as a dictionary.

Implemented for compatibility with scikit-learn.

Returns

dict: Attribute names mapped to their current values.

get_predict_operation_log()¶

Retrieve the operation log produced during prediction.

Returns

DataFrame: Reference to the OPERATION_LOG table containing detailed APL logs from the last predict() call.

Raises

AttributeError: If predict() has not been called yet.

get_summary()¶

Retrieve the summary table produced during model training.

Returns

DataFrame: Reference to the SUMMARY table containing the execution summary of the last model training.

Raises

FitIncompleteError: If fit() has not been called yet.

is_fitted()¶

Checks if the model can be saved. To be overridden if the model is not stored in model_ attribute.

Returns

bool: True if the model is ready to be saved.

load_model(schema_name, table_name, oid=None)¶

Loads the model from a table.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr: The schema name.
table_namestr: The table name.
oidstr, optional: If the table contains several models, the OID identifies which model to load. If not provided, the entire table is read.

save_artifact(artifact_df, schema_name, table_name, if_exists='fail', new_oid=None)¶

Save an artifact (a temporary table) into a permanent table. The model has to be trained beforehand.

Parameters

artifact_dfDataFrame

The artifact created after fit() or predict() are called.

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises a FitIncompleteError.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value replaces the OID column when inserting rows. Useful when saving multiple models into the same table.

Examples

>>> myModel.save_artifact(artifact_df=myModel.indicators_,
...                       schema_name='MySchema',
...                       table_name='MyModel_Indicators',
...                       if_exists='replace')

save_model(schema_name, table_name, if_exists='fail', new_oid=None)¶

Save the model into a HANA table.

The model must be trained beforehand. It can be saved into a new table (if_exists='replace') or appended to an existing table (if_exists='append'). When appending, an optional new_oid can be provided; it must be unique.

Warning

This method is deprecated. Please use ModelStorage.

Parameters

schema_namestr

The schema name.

table_namestr

The table name.

if_exists{'fail', 'replace', 'append'}, optional

Behaviour when the table already exists. Default is 'fail'.

'fail' — raises an error.
'replace' — drops the table before inserting new values.
'append' — inserts new values into the existing table.

new_oidstr, optional

If provided, this value is used as the OID when saving. Useful when saving multiple models into the same table.

Notes

The model is stored in a table with the following columns:

OID NVARCHAR(50) — model identifier
FORMAT NVARCHAR(50) — APL technical format info
LOB CLOB — binary content of the model

schedule_fit(output_table_name_model, output_table_name_log, output_table_name_summary, output_table_name_indicators, **schedule_kwargs)¶

Create a HANA scheduler job for model fitting.

Wraps create_training_schedule(), allowing output table names to be specified directly as arguments.

Parameters

output_table_name_modelstr: The output table name for the model binary.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
output_table_name_indicatorsstr: The output table name for the model indicators.
**schedule_kwargsdict: Additional arguments forwarded to create_training_schedule().

Raises

ValueError: If the connection context is not set (model not yet fitted).

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.schedule_fit(
...     output_table_name_model='OUTPUT_MODEL_BINARY',
...     output_table_name_log='OUTPUT_FIT_LOG',
...     output_table_name_summary='OUTPUT_SUMMARY_LOG',
...     output_table_name_indicators='OUTPUT_FIT_INDICATORS',
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

schedule_predict(input_table_name_model, output_table_name_applyout, output_table_name_log, output_table_name_summary, **schedule_kwargs)¶

Create a HANA scheduler job for model prediction.

Wraps create_applying_schedule(), allowing output table names to be specified directly as arguments.

Parameters

input_table_name_modelstr: The input table name for the model binary.
output_table_name_applyoutstr: The output table name for the prediction data.
output_table_name_logstr: The output table name for the log data.
output_table_name_summarystr: The output table name for the model summary.
**schedule_kwargsdict: Additional arguments forwarded to create_applying_schedule().

Raises

ValueError: If the connection context is not set, or if input_table_name_model is not provided.

Examples

>>> model = GradientBoostingBinaryClassifier()
>>> model.fit(
...     data=data,
...     key='id',
...     label='class')
>>> model.predict(data)
>>> model.schedule_predict(
...     input_table_name_model='MODEL_BINARY',
...     output_table_name_applyout="OUTPUT_PREDICT_APPLYOUT",
...     output_table_name_log="OUTPUT_PREDICT_LOG",
...     output_table_name_summary="OUTPUT_PREDICT_SUMMARY",
...     job_name=job_name,
...     obj=model,
...     cron="* * * mon,tue,wed,thu,fri 1 23 45",
...     procedure_name=procedure_name,
...     force=True)

set_params(**parameters)¶

Set attributes of the current model.

Implemented for compatibility with scikit-learn.

Parameters

**parametersdict: The attribute names and their values.

Returns

self: The current instance.

set_scale_out(route_to=None, no_route_to=None, route_by=None, route_by_cardinality=None, data_transfer_cost=None, route_optimization_level=None, workload_class=None)¶

Specify hints for a scale-out environment.

The execution of APL functions can then be routed to a specific computation node. If all parameters are None, all existing hints are cleared.

Parameters

route_tostr, optional: Routes the query to the specified volume ID or service type.
no_route_tostr or list of str, optional: Avoids query routing to a specified volume ID or service type.
route_bystr, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s).
route_by_cardinalitystr or list of str, optional: Routes the query to the hosts related to the base table(s) of the specified projection view(s) with the highest cardinality from the input list.
data_transfer_costint, optional: Guides the optimizer to use the weighting factor for the data transfer cost. The value 0 ignores the data transfer cost.
route_optimization_level{'minimal', 'all'}, optional: Guides the optimizer to compile with route_optimization_level 'minimal' or to default to route_optimization_level. If the 'minimal' compiled plan is cached, it compiles once more using the default optimization level during the first execution. Primarily used to shorten statement routing decisions during initial compilation.
workload_classstr, optional: Routes the query via workload class. route_to has higher precedence than workload_class.

Examples

>>> from hana_ml.algorithms.apl.gradient_boosting_classification import GradientBoostingBinaryClassifier
>>> model = GradientBoostingBinaryClassifier()
>>> # Routes the execution to a specific volume ID.
>>> model.set_scale_out(route_to=1025)
>>> # Routes the execution to a specific service type.
>>> # model.set_scale_out(route_to='computeserver')
>>> # Maps the execution to a specific workload class.
>>> # model.set_scale_out(workload_class="WC4")
>>> # Activates the SQL trace
>>> # connection_context.sql_tracer.enable_sql_trace(True)
>>> model.fit(data=hdb_df, key='KEY', label='Y')
>>> # You can check whether the queries were effectively routed by querying:
>>> # SELECT HOST, VOLUME_ID, APPLICATION_NAME, STATEMENT_STRING FROM M_SQL_PLAN_CACHE.