teradataml 20.0.0.8__py3-none-any.whl

teradataml/data/docs/byom/docs/ONNXPredict.py

@@ -0,0 +1,283 @@
+def ONNXPredict(newdata=None, modeldata=None, accumulate=None, model_output_fields=None,
+                overwrite_cached_models="false", show_model_input_fields_map=False,
+                model_input_fields_map=None, is_debug=False, **generic_arguments):
+
+    """
+    DESCRIPTION:
+        The ONNXPredict() function is used to score data in Vantage with a model that has
+        been created outside Vantage and exported to Vantage using ONNX format.
+
+        For classical machine learning models on structured data, Vantage has a large set
+        of transformation functions in both the Vantage Analytics Library and Analytics Database
+        Analytic functions. User can use these functions to prepare the input data that the
+        classical machine learning models expect. However, there are no transformation or
+        conversion functions in Vantage to prepare tensors for unstructured data (text,
+        images, video and audio) for ONNX models. The data must be preprocessed before
+        loading to Vantage to conform the tensors into a shape that the ONNX models expect.
+        As long as the data is in the form expected by your ONNX model, it can be scored by
+        ONNXPredict().
+        ONNXPredict() supports models in ONNX format. Several training frameworks support
+        native export functionality to ONNX, such as Chainer, Caffee2, and PyTorch.
+        User can also convert models from several toolkits like scikit-learn, TensorFlow,
+        Keras, XGBoost, H2O, and Spark ML to ONNX.
+
+
+    PARAMETERS:
+        newdata:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the input test data.
+            Types: teradataml DataFrame
+
+        modeldata:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the model data
+            to be used for scoring.
+            Note:
+                * Use `retrieve_byom()` to get the teradataml DataFrame that contains the model.
+            Types: teradataml DataFrame
+
+        accumulate:
+            Required Argument.
+            Specifies the name(s) of input teradataml DataFrame column(s) to
+            copy to the output.
+            Types: str OR list of Strings (str) OR Feature OR list of Features
+
+        model_output_fields:
+            Optional Argument.
+            Specifies the column(s) of the json output that the user wants to
+            specify as individual columns instead of the entire json_report.
+            Types: str OR list of Strings (str)
+
+        overwrite_cached_models:
+            Optional Argument.
+            Specifies the model name that needs to be removed from the cache.
+            When a model loaded into the memory of the node fits in the cache,
+            it stays in the cache until being evicted to make space for another
+            model that needs to be loaded. Therefore, a model can remain in the
+            cache even after the completion of function execution. Other functions
+            that use the same model can use it, saving the cost of reloading it
+            into memory. User should overwrite a cached model only when it is updated,
+            to make sure that the Predict function uses the updated model instead
+            of the cached model.
+            Note:
+                Do not use the "overwrite_cached_models" argument except when user
+                is trying to replace a previously cached model. Using the argument
+                in other cases, including in concurrent queries or multiple times
+                within a short period of time lead to an OOM error.
+            Default Value: "false"
+            Permitted Values: true, t, yes, y, 1, false, f, no, n, 0, *,
+                              current_cached_model
+            Types: str
+
+        show_model_input_fields_map:
+            Optional Argument.
+            Specifies When set to 'True', the function does not predict the "newdata",
+            instead shows the currently defined fields fully expanded.
+            Example:
+                If "model_input_fields_map" is x=[1:4] and "show_model_input_fields_map"
+                is set to 'True', the output is returned as a varchar column:
+                    model_input_fields_map='x=sepal_len,sepal_wid,petal_len,petal_wid'
+            When "model_input_fields_map" is not specified, the expected default
+            mapping is based on the ONNX inputs defined in the model is shown.
+            When set to 'False', which is the default value the function predict the
+            "newdata".
+            Default Value: False
+            Types: bool
+
+        model_input_fields_map:
+            Optional Argument.
+            Specifies the output fields to add as individual columns instead of the
+            entire JSON output.
+            Types: str OR list of Strings (str)
+
+        is_debug:
+            Optional Argument.
+            Specifies whether debug statements are added to a trace table or not.
+            When set to True, debug statements are added to a trace table that must
+            be created beforehand.
+            Notes:
+                * Only available with BYOM version 3.00.00.02 and later.
+                * To save logs for debugging, user can create an error log by using
+                  the is_debug=True parameter in the predict functions.
+                  A database trace table is used to collect this information which
+                  does impact performance of the function, so using small data input
+                  sizes is recommended.
+                * To generate this log, user must do the following:
+                      1. Create a global trace table with columns vproc_ID BYTE(2),
+                         Sequence INTEGER, Trace_Output VARCHAR(31000)
+                      2. Turn on session function tracing:
+                           SET SESSION FUNCTION TRACE USING '' FOR TABLE <trace_table_name_created_in_step_1>;
+                      3. Execute function with "is_debug" set to True.
+                      4. Debug information is logged to the table created in step 1.
+                      5. To turn off the logging, either disconnect from the session or
+                         run following SQL:
+                           SET SESSION FUNCTION TRACE OFF;
+                      The trace table is temporary and the information is deleted if user
+                      logs off from the session. If long term persistence is necessary,
+                      user can copy the table to a permanent table before leaving the
+                      session.
+            Default Value: False
+            Types: bool
+
+        **generic_arguments:
+            Specifies the generic keyword arguments SQLE functions accept. Below
+            are the generic keyword arguments:
+                persist:
+                    Optional Argument.
+                    Specifies whether to persist the results of the
+                    function in a table or not. When set to True,
+                    results are persisted in a table; otherwise,
+                    results are garbage collected at the end of the
+                    session.
+                    Default Value: False
+                    Types: bool
+
+                volatile:
+                    Optional Argument.
+                    Specifies whether to put the results of the
+                    function in a volatile table or not. When set to
+                    True, results are stored in a volatile table,
+                    otherwise not.
+                    Default Value: False
+                    Types: bool
+
+            Function allows the user to partition, hash, order or local
+            order the input data. These generic arguments are available
+            for each argument that accepts teradataml DataFrame as
+            input and can be accessed as:
+                * "<input_data_arg_name>_partition_column" accepts str or
+                  list of str (Strings) or PartitionKind
+                * "<input_data_arg_name>_hash_column" accepts str or list
+                  of str (Strings)
+                * "<input_data_arg_name>_order_column" accepts str or list
+                  of str (Strings)
+                * "local_order_<input_data_arg_name>" accepts boolean
+            Note:
+                These generic arguments are supported by teradataml if
+                the underlying SQL Engine function supports, else an
+                exception is raised.
+
+    RETURNS:
+        Instance of ONNXPredict.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as ONNXPredictObj.<attribute_name>.
+        Output teradataml DataFrame attribute name is:
+            result
+
+
+    RAISES:
+        TeradataMlException, TypeError, ValueError
+
+
+    EXAMPLES:
+        # Notes:
+        #     1. Get the connection to Vantage to execute the function.
+        #     2. One must import the required functions mentioned in
+        #        the example from teradataml.
+        #     3. Function will raise error if not supported on the Vantage
+        #        user is connected to.
+        #     4. To execute BYOM functions, set 'configure.byom_install_location' to the
+        #        database name where BYOM functions are installed.
+
+        # Import required libraries / functions.
+        import os, teradataml
+        from teradataml import DataFrame, load_example_data, configure, execute_sql
+        from teradataml import save_byom, retrieve_byom, display_analytic_functions
+
+        # Load the example data.
+        load_example_data("byom", ["iris_test"])
+
+        # Create teradataml DataFrame objects.
+        iris_test = DataFrame("iris_test")
+
+        # Set install location of BYOM functions.
+        configure.byom_install_location = "mldb"
+
+        # Check the list of available analytic functions.
+        display_analytic_functions(type="BYOM")
+
+        # Load model file into Vantage.
+        model_file_path = os.path.join(os.path.dirname(teradataml.__file__), "data", "models")
+        skl_model_file = os.path.join(model_file_path,
+                                      "iris_db_dt_model_sklearn.onnx")
+        skl_floattensor_model_file = os.path.join(model_file_path,
+                                                  "iris_db_dt_model_sklearn_floattensor.onnx")
+
+        # Save ONNX models.
+        save_byom("iris_db_dt_model_sklearn",
+                  skl_model_file, "byom_models")
+        save_byom("iris_db_dt_model_sklearn_floattensor",
+                  skl_floattensor_model_file, "byom_models")
+
+        # Retrieve ONNX model.
+        # The 'iris_db_dt_model_sklearn' created with each input variable mapped
+        # to a single input tensor, then converted this model into ONNX format
+        # with scikit-learn-onnx, and then used to predict the flower species.
+        # This model trained using iris_test dataset with scikit-learn.
+        skl_model = retrieve_byom("iris_db_dt_model_sklearn",
+                                  table_name="byom_models")
+
+        # The 'iris_db_dt_model_sklearn_floattensor' created by using an input array of
+        # four float32 values and named float_input, then converted this model into ONNX
+        # format with scikit-learn-onnx, and then used to predict the flower species.
+        # This model trained using iris_test dataset with scikit-learn.
+        skl_floattensor_model = retrieve_byom("iris_db_dt_model_sklearn_floattensor",
+                                    table_name="byom_models")
+
+        # Example 1: Example performs prediction with ONNXPredict function using trained
+        #            'skl_model' model in onnx format generated outside of Vantage.
+        ONNXPredict_out = ONNXPredict(accumulate="id",
+                                      newdata=iris_test,
+                                      modeldata=skl_model)
+
+        # Print the results.
+        print(ONNXPredict_out.result)
+
+
+        # Example 2: Example performs prediction with ONNXPredict function using trained
+        #            'skl_floattensor_model' model in onnx format generated
+        #            outside of Vantage, where input DataFrame columns match the order
+        #            used when generating the model, by specifying "model_input_fields_map"
+        #            to define the columns.
+        ONNXPredict_out1 = ONNXPredict(accumulate="id",
+                                       model_output_fields="output_probability",
+                                       overwrite_cached_models="*",
+                                       model_input_fields_map='float_input=sepal_length, sepal_width, petal_length, petal_width',
+                                       newdata=iris_test,
+                                       modeldata=skl_floattensor_model)
+
+
+        # Print the result DataFrame.
+        print(ONNXPredict_out1.result)
+
+        # Example 3: Example to show case the trace table usage using
+        #            is_debug=True.
+
+        # Create the trace table.
+        crt_tbl_query = 'CREATE GLOBAL TEMPORARY TRACE TABLE BYOM_Trace \
+                        (vproc_ID	BYTE(2) \
+                        ,Sequence	INTEGER \
+                        ,Trace_Output VARCHAR(31000) CHARACTER SET LATIN NOT CASESPECIFIC) \
+                        ON COMMIT PRESERVE ROWS;'
+        execute_sql(crt_tbl_query)
+
+        # Turn on tracing for the session.
+        execute_sql("SET SESSION FUNCTION TRACE USING '' FOR TABLE BYOM_Trace;")
+
+        # Execute the ONNXPredict() function using is_debug=True.
+        ONNXPredict_out2 = ONNXPredict(accumulate="id",
+                                      newdata=iris_test,
+                                      modeldata=skl_model,
+                                      is_debug=True)
+
+        # Print the results.
+        print(ONNXPredict_out2.result)
+
+        # View the trace table information.
+        trace_df = DataFrame.from_table("BYOM_Trace")
+        print(trace_df)
+
+        # Turn off tracing for the session.
+        execute_sql("SET SESSION FUNCTION TRACE OFF;")
+
+    """

teradataml/data/docs/byom/docs/ONNXSeq2Seq.py

@@ -0,0 +1,255 @@
+def ONNXSeq2Seq(newdata=None, modeldata=None, tokenizerdata=None, accumulate=None, model_output_tensor=None,
+                encode_max_length=512, show_model_properties=False, output_length=1000,
+                overwrite_cached_models="false", is_debug=False, skip_special_tokens=True,
+                enable_memory_check=False, const_=None, **generic_arguments):
+    """
+    DESCRIPTION:
+        The ONNXSeq2Seq() function applies a sequence-to-sequence model that has 
+        been created outside Vantage and exported to Vantage in ONNX format 
+        to input data within Teradata Vantage.
+        
+    PARAMETERS:
+        newdata:
+            Required Argument.
+            Specifies the input teradataml DataFrame that contains
+            the data to be scored.
+            Types: teradataml DataFrame
+
+        modeldata:
+            Required Argument.
+            Specifies the model teradataml DataFrame to be used for
+            scoring.
+            Note:
+                * Use `retrieve_byom()` to get the teradataml DataFrame that contains the model.
+            Types: teradataml DataFrame
+
+        tokenizerdata:
+            Required Argument.
+            Specifies the tokenizer teradataml DataFrame
+            which contains the tokenizer json file.
+            Types: teradataml DataFrame
+
+        accumulate:
+            Required Argument.
+            Specifies the name(s) of input teradataml DataFrame column(s) to
+            copy to the output. By default, the function copies all input
+            teradataml DataFrame columns to the output.
+            Types: str OR list of Strings (str) OR Feature OR list of Features
+
+        model_output_tensor:
+            Required Argument.
+            Specifies the column of the model's possible output fields
+            that the user wants to calculate and output.
+            Types: str
+
+        encode_max_length:
+            Optional Argument.
+            Specifies the maximum length of the tokenizer output token
+            encodings(only applies for models with symbolic dimensions).
+            Default Value: 512
+            Types: int
+
+        show_model_properties:
+            Optional Argument.
+            Specifies the default or expanded "model_input_fields_map" based on
+            input model for defaults or "model_input_fields_map" for expansion.
+            Default Value: False
+            Types: bool
+
+        output_length:
+            Optional Argument.
+            Specifies the output length for the model sequence output, in number of 
+            characters for the VARCHAR output. If the value exceeds the maximum Unicode 
+            VARCHAR size of 32000, a CLOB is created automatically.
+            Default Value: 1000
+            Types: int
+
+        overwrite_cached_models:
+            Optional Argument.
+            Specifies the model name that needs to be removed from the cache.
+            When a model loaded into the memory of the node fits in the cache,
+            it stays in the cache until being evicted to make space for another
+            model that needs to be loaded. Therefore, a model can remain in the
+            cache even after the completion of function execution. Other functions
+            that use the same model can use it, saving the cost of reloading it
+            into memory. User should overwrite a cached model only when it is updated,
+            to make sure that the Predict function uses the updated model instead
+            of the cached model.
+            Note:
+                Do not use the "overwrite_cached_models" argument except when user
+                is trying to replace a previously cached model. Using the argument
+                in other cases, including in concurrent queries or multiple times
+                within a short period of time lead to an OOM error.
+            Default Value: "false"
+            Permitted Values: true, t, yes, y, 1, false, f, no, n, 0, *,
+                              current_cached_model
+            Types: str
+
+        is_debug:
+            Optional Argument.
+            Specifies whether debug statements are added to a trace table or not.
+            When set to True, debug statements are added to a trace table that must
+            be created beforehand.
+            Notes:
+                * Only available with BYOM version 3.00.00.02 and later.
+                * To save logs for debugging, user can create an error log by using
+                  the is_debug=True parameter in the predict functions.
+                  A database trace table is used to collect this information which
+                  does impact performance of the function, so using small data input
+                  sizes is recommended.
+                * To generate this log, user must do the following:
+                      1. Create a global trace table with columns vproc_ID BYTE(2),
+                         Sequence INTEGER, Trace_Output VARCHAR(31000)
+                      2. Turn on session function tracing:
+                           SET SESSION FUNCTION TRACE USING '' FOR TABLE <trace_table_name_created_in_step_1>;
+                      3. Execute function with "is_debug" set to True.
+                      4. Debug information is logged to the table created in step 1.
+                      5. To turn off the logging, either disconnect from the session or
+                         run following SQL:
+                           SET SESSION FUNCTION TRACE OFF;
+                      The trace table is temporary and the information is deleted if user
+                      logs off from the session. If long term persistence is necessary,
+                      user can copy the table to a permanent table before leaving the
+                      session.
+            Default Value: False
+            Types: bool
+
+        enable_memory_check:
+            Optional Argument.
+            Specifies whether there is enough native memory for large models.
+            Default Value: True
+            Types: bool
+
+        skip_special_tokens:
+            Optional Argument.
+            Specifies whether to skip special tokens in the output.
+            Default Value: True
+            Types: bool
+
+        const_*:
+            Optional Argument.
+            Specifies the constant value to be used as a model input by using 
+            the argument name const_<field_name>. Providing constant values as 
+            parameters reduces system overhead, since the value will not be 
+            added to every row being scored.
+            Types: str
+
+        **generic_arguments:
+            Specifies the generic keyword arguments SQLE functions accept. Below
+            are the generic keyword arguments:
+                persist:
+                    Optional Argument.
+                    Specifies whether to persist the results of the
+                    function in a table or not. When set to True,
+                    results are persisted in a table; otherwise,
+                    results are garbage collected at the end of the
+                    session.
+                    Default Value: False
+                    Types: bool
+
+                volatile:
+                    Optional Argument.
+                    Specifies whether to put the results of the
+                    function in a volatile table or not. When set to
+                    True, results are stored in a volatile table,
+                    otherwise not.
+                    Default Value: False
+                    Types: bool
+
+            Function allows the user to partition, hash, order or local
+            order the input data. These generic arguments are available
+            for each argument that accepts teradataml DataFrame as
+            input and can be accessed as:
+                * "<input_data_arg_name>_partition_column" accepts str or
+                  list of str (Strings) or PartitionKind
+                * "<input_data_arg_name>_hash_column" accepts str or list
+                  of str (Strings)
+                * "<input_data_arg_name>_order_column" accepts str or list
+                  of str (Strings)
+                * "local_order_<input_data_arg_name>" accepts boolean
+            Note:
+                These generic arguments are supported by teradataml if
+                the underlying SQL Engine function supports, else an
+                exception is raised.
+
+    RETURNS:
+        Instance of ONNXSeq2Seq.
+        Output teradataml DataFrame can be accessed using attribute
+        references, such as  ONNXSeq2Seq.<attribute_name>.
+        Output teradataml DataFrame attribute name is:
+            result
+
+
+    RAISES:
+        TeradataMlException, TypeError, ValueError
+
+
+    EXAMPLES:
+        # Notes:
+        #     1. Get the connection to Vantage to execute the function.
+        #     2. One must import the required functions mentioned in
+        #        the example from teradataml.
+        #     3. Function will raise error if not supported on the Vantage
+        #        user is connected to.
+        #     4. To execute BYOM functions, set 'configure.byom_install_location' to the
+        #        database name where BYOM functions are installed.
+
+        # Import required libraries / functions.
+        import os, teradataml
+        from teradataml import get_connection, DataFrame
+        from teradataml import save_byom, retrieve_byom, load_example_data
+        from teradataml import configure, display_analytic_functions, execute_sql
+
+        # Load example data.
+        load_example_data("byom", "JulesBelvezeDummyData")
+
+        # Create teradataml DataFrame objects.
+        jules_data = DataFrame.from_table("JulesBelvezeDummyData")
+
+        # Assigning txt column name to rev_txt column.
+        jules_data = jules_data[jules_data.id <= 5]
+        jules_data = jules_data.assign(txt=jules_data.content)
+
+        # Set install location of BYOM functions.
+        configure.byom_install_location = "td_mldb"
+
+        # Check the list of available analytic functions.
+        display_analytic_functions(type="BYOM")
+        
+        # Note: User must have the model and tokenizer data already loaded in the database.
+        # Retrieve model.
+        modeldata = retrieve_byom("t5-small-headline-generator_fixed", table_name="seq_models")
+        tokenizerdata = retrieve_byom("t5-small-headline-generator_fixed", table_name="seq_tokenizers")
+
+        # Assigning tokenizer_id, tokenizer to model_id, model in Seq2Seq_tokenizers.
+        tokenizerdata_a1 = tokenizerdata.assign(tokenizer_id=tokenizerdata.model_id)
+        tokenizerdata_a2 = tokenizerdata_a1.assign(tokenizer=tokenizerdata_a1.model)
+
+        # Example 1: Showcasing the model properties of t5-small-headline-generator_fixed model
+        #            that has been created outside the Vantage.
+        ONNXSeq2Seq_out = ONNXSeq2Seq(modeldata = modeldata,
+                                      tokenizerdata=tokenizerdata_a2.select(['tokenizer_id', 'tokenizer']),
+                                      newdata=jules_data.select(["id", "txt"]),
+                                      accumulate='id',
+                                      model_output_tensor= 'sequences',
+                                      show_model_properties=True)
+
+        # Print the results.
+        print(ONNXSeq2Seq_out.result)
+
+        # Example 2: Using ONNXSeq2Seq with constant values.
+        ONNXSeq2Seq_out = ONNXSeq2Seq(modeldata = modeldata,
+                                      tokenizerdata=tokenizerdata_a2.select(['tokenizer_id', 'tokenizer']),
+                                      newdata=jules_data.select(["id", "txt"]),
+                                      accumulate='id',
+                                      model_output_tensor= 'sequences',
+                                      const_min_length=10,
+                                      const_max_length=84,
+                                      const_num_beams=4,
+                                      const_repetition_penalty=1.2,
+                                      const_length_penalty=2.0,
+                                      const_num_return_sequences=1)
+
+        # Print the results.
+        print(ONNXSeq2Seq_out.result)
+    """