.. _model_state:

Model State for Real-Time Scoring
=================================
.. currentmodule :: hana_ml.algorithms.pal

When a model is applied in scoring functions(e.g. `predict()`, `score()`, `transform()`) in
**hana_ml.algorithms.pal** package (also in SAP HANA PAL), two steps are performed sequentially:
firstly the model is parsed, secondly the parsed model is applied to the scoring data.
This is the common way that scoring functions works in SAP HANA PAL, and usually it won't be an issue.
However, for scenarios where the trained model is complex enough while the model is called by scoring functions multiple times,
parsing the model shall take too much time compared with the total execution time of scoring functions.
In such scenarios, it is definitely unwise to parse the model over and over again.

**hana_ml.algorithms.pal** package provides the functionality for running the two sequential steps in scoring
functions separately, based on the mechanism implemented in SAP HANA PAL. Basically, model parsing(de-serializing
the model content from the database table and converting it into model object) could be executed alone only once,
and then the parsed model could be kept and repeatedly applied to any incoming scoring data.

In **hana_ml.algorithms.pal** package, there are a family of classes that support the splitting of model parsing
and scoring execution. Basically, the following class methods get involved for state-enabled scoring:

   - `create_model_state()` : Should be called in the presence of a trained model, the model content is
     read from the database tables, parsed, and finally kept in container called `state`. Identifier
     of the model state is stored in a database table and is assigned to the `state` attributes of the
     class object for reference.

   - scoring functions(e.g. `predict()`, `score()`, `transform()`) : After a model state has been created,
     we can directly call the corresponding scoring methods of the python class, then parsed model is loaded
     automatically from the model state for scoring.

   - `delete_model_state()` : When the parse model becomes obsolete, it is necessary to free up the container
     for the model states since it consumes memory. This can easily realized by calling the `delete_model_state()`
     methods of the class.

**Algorithms in hana_ml.algorithms.pal Package that Supports State-Enabled Scoring**

    * :class:`hana_ml.algorithms.pal.svm.SVC`
    * :class:`hana_ml.algorithms.pal.svm.SVR`
    * :class:`hana_ml.algorithms.pal.svm.SVRanking`
    * :class:`hana_ml.algorithms.pal.svm.OneClassSVM`
    * :class:`hana_ml.algorithms.pal.trees.RDTClassifier`
    * :class:`hana_ml.algorithms.pal.trees.RDTRegressor`
    * :class:`hana_ml.algorithms.pal.trees.DecisionTreeClassifier`
    * :class:`hana_ml.algorithms.pal.trees.DecisionTreeRegressor`
    * :class:`hana_ml.algorithms.pal.trees.HybridGradientBoostingClassifier`
    * :class:`hana_ml.algorithms.pal.trees.HybridGradientBoostingRegressor`
    * :class:`hana_ml.algorithms.pal.clustering.KMeans`
    * :class:`hana_ml.algorithms.pal.clustering.DBSCAN`
    * :class:`hana_ml.algorithms.pal.som.SOM`
    * :class:`hana_ml.algorithms.pal.decomposition.LatentDirichletAllocation`
    * :class:`hana_ml.algorithms.pal.decomposition.PCA`
    * :class:`hana_ml.algorithms.pal.decomposition.CATPCA`
    * :class:`hana_ml.algorithms.pal.naive_bayes.NaiveBayes`
    * :class:`hana_ml.algorithms.pal.neural_network.MLPClassifier`
    * :class:`hana_ml.algorithms.pal.neural_network.MLPRegressor`
    * :class:`hana_ml.algorithms.pal.linear_model.LinearRegression`
    * :class:`hana_ml.algorithms.pal.linear_model.LogisticRegression`
    * :class:`hana_ml.algorithms.pal.recommender.FRM`
    * :class:`hana_ml.algorithms.pal.recommender.ALS`
    * :class:`hana_ml.algorithms.pal.crf.CRF`
    * :class:`hana_ml.algorithms.pal.neighbors.KNNClassifier`
    * :class:`hana_ml.algorithms.pal.neighbors.KNNRegressor`
    * :class:`hana_ml.algorithms.pal.unified_classification.UnifiedClassification`
    * :class:`hana_ml.algorithms.pal.unified_regression.UnifiedRegression`