teradataml 17.20.0.7__py3-none-any.whl → 20.0.0.1__py3-none-any.whl

teradataml/data/docs/sqle/docs_17_20/XGBoostPredict.py

@@ -1,275 +1,281 @@
-def XGBoostPredict(newdata = None, object = None, id_column = None, num_boosted_tree = 1000,
-                   iter_num = 3, accumulate = None, output_prob = False, model_type = "REGRESSION",
-                   output_responses = None,  **generic_arguments):
-    """
-    DESCRIPTION:
-        The XGBoostPredict() function runs the predictive algorithm based on the model generated
-        by XGBoost(). The XGBoost() function, also known as eXtreme Gradient Boosting, performs
-        classification or regression analysis on datasets.
-
-        XGBoostPredict() performs prediction for test input data using multiple simple trees in
-        the trained model. The test input data should have the same attributes as used during
-        the training phase, which can be up to 2046. These attributes are used to score based
-        on the trees in the model.
-
-        The output contains prediction for each data point in the test data based on regression
-        or classification. The prediction probability is computed based on the majority vote
-        from participating trees. A higher probability implies a more confident prediction by
-        the model. Majority of the trees result in the same prediction.
-
-        Notes:
-            * The processing time is controlled by (proportional to):
-                * The number of boosted trees used for prediction from the model (controlled
-                  by "num_boosted_trees").
-                * The number of iterations (sub-trees) used for prediction from the model
-                  in each boosted tree (controlled by "iter_num").
-
-            A careful choice of these parameters can be used to control the processing time.
-            When the boosted trees size grows more than what can fit in memory, the trees are
-            cached in a local spool space, which may impact the performance of the function
-            compared to the case when all trees fit in memory.
-
-    PARAMETERS:
-        object:
-            Required Argument.
-            Specifies the teradataml DataFrame containing the model data generated by XGBoost()
-            function or the instance of XGBoost.
-            Types: teradataml DataFrame or XGBoost
-
-        newdata:
-            Required Argument.
-            Specifies the teradataml DataFrame containing the input data.
-            Types: teradataml DataFrame
-
-        id_column:
-            Required Argument.
-            Specifies the input data column name that contains a unique
-            identifier for each test point in the test set.
-            Note:
-                * Input column names with double quotation marks are not allowed for this function.
-            Types: str
-
-        num_boosted_tree:
-            Optional Argument.
-            Specifies how many boosted trees to use to make predictions.
-            A combination of both 'task_Index' and 'tree_num' in the model table determines
-            the AMPID and number of trees generated by that AMP. As we order the model table
-            with these two arguments, the number of boosted trees that are loaded are based
-            on this order.
-            For example, if there are two AMPs on the system and AMP 1 ('task_index': 0) generates
-            three boosted trees ('tree_num':1,2,3), while AMP 2 ('task_index': 1) generate two boosted
-            trees ('tree_num': 1,2). Then, "num_boosted_tree"(4) loads three boosted trees from AMP1
-            ('task_index': 0) and one boosted tree from AMP2 ('task_index': 1).
-            As one boosted tree is skipped altogether from loading it in memory and making predictions,
-            this results in a faster elapsed time for queries compared to loading all trees in memory.
-            However, this can also lead to loss in prediction accuracy. In addition, any unique tree
-            is determined by 'task_index', 'tree_id' and 'iter_num' in the model table.
-            Default Value: 1000
-            Types: int
-
-        iter_num:
-            Optional Argument.
-            Specifies how many iterations to load for each boosted tree to make predictions.
-            For example, AMP1 ('task_index':0) generates three boosted trees ('tree_num': 1,2,3)
-            with each tree having four iterations ('iter':1,2,3,4). There are 12 trees in total.
-            "iter_num"(2) only loads two iterations per boosted tree, that is, only six trees
-            are loaded for this example.
-            As some trees are skipped from being loaded in memory and predictions are made
-            without them, this results in a faster elapsed time for queries compared to
-            loading all trees in memory, but also lead to loss in prediction accuracy.
-            Default Value: 3
-            Types: int
-
-        accumulate:
-            Optional Argument.
-            Specifies the name(s) of input teradataml DataFrame column(s) to copy to the
-            output. By default, the function copies no input teradataml DataFrame columns
-            to the output.
-            Types: str OR list of Strings (str)
-
-        output_prob:
-            Optional Argument.
-            Specifies whether the function should output the probability for each
-            "output_responses".
-            Notes:
-                * If "output_prob" is true and "output_responses" are not provided,
-                  output the probability of the predicted class.
-                * The "output_prob" argument works only when "model_type" is
-                  'Classification'.
-            Default Value: False
-            Types: bool
-
-        model_type:
-            Optional Argument.
-            Specifies whether the analysis is a regression (continuous response variable) or
-            a multiple-class classification (predicting result from the number of classes).
-            For 'Classification', output the prediction column as integers. These integral
-            values represent different categories, and so are better observed as an integer
-            column. To make the output schema for prediction column as an integer, set
-            "model_type" as 'Classification'.
-            Permitted Values:
-                * Regression
-                * Classification
-            Default Value: Regression
-            Types: str
-
-        output_responses:
-            Optional Argument.
-            Specifies the classes for which to output probabilities.
-            Notes:
-                * If "output_prob" is true and "output_responses" are not provided,
-                  output the probability of the predicted class.
-                * The "output_responses" argument works only when "model_type" is
-                  'Classification'.
-            Types: str OR list of str(s)
-
-        **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)
-                * "<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 SQLE Engine function supports, else an
-                exception is raised.
-
-    RETURNS:
-        Instance of XGBoostPredict.
-        Output teradataml DataFrames can be accessed using attribute
-        references, such as XGBoostPredictObj.<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.
-
-        # Load the example data.
-        load_example_data("teradataml", "titanic")
-        load_example_data("byom", "iris_input")
-
-        # Create teradataml DataFrame objects.
-        titanic = DataFrame.from_table("titanic")
-        iris_input = DataFrame("iris_input")
-
-        # Check the list of available analytic functions.
-        display_analytic_functions()
-
-        # Example 1: This example takes titanic data as input, and generates the Regression
-        #            model using XGBoost(). Using XGBoostPredict() function to predict the
-        #            fare with the Regression model generated by XGBoost().
-
-        # Create 2 samples of input data - sample 1 will have 80% of total rows and
-        # sample 2 will have 20% of total rows.
-        titanic_sample = titanic.sample(frac=[0.8, 0.2])
-
-        # Create train dataset from sample 1 by filtering on "sampleid" and drop
-        # "sampleid" column as it is not required for training model.
-        titanic_train = titanic_sample[titanic_sample.sampleid == "1"].drop("sampleid", axis = 1)
-
-        # Create test dataset from sample 2 by filtering on "sampleid" and
-        # drop "sampleid" column as it is not required for scoring.
-        titanic_test = titanic_sample[titanic_sample.sampleid == "2"].drop("sampleid", axis = 1)
-
-        XGBoost_out_1 = XGBoost(data=titanic_train,
-                                input_columns=["age", "survived", "pclass"],
-                                response_column = 'fare',
-                                max_depth=3,
-                                lambda1 = 1000.0,
-                                model_type='Regression',
-                                seed=-1,
-                                shrinkage_factor=0.1,
-                                iter_num=2)
-
-        # XGBoostPredict() predicts the result using generated Regression model by
-        # XGBoost() and "newdata".
-        XGBoostPredict_out_1 = XGBoostPredict(newdata=titanic_test,
-                                              object=XGBoost_out_1.result,
-                                              id_column='passenger',
-                                              object_order_column=['task_index', 'tree_num',
-                                                                   'iter', 'tree_order'])
-
-        # Print the result DataFrame.
-        print(XGBoostPredict_out_1.result)
-
-        # Example 2: This example takes titanic data, and generates the Classification
-        #            model using XGBoost(). Using XGBoostPredict() function to predict the fare
-        #            with the Classification model generated by XGBoost(). Provides the classes for
-        #            which to output the probabilities.
-
-        # Create 2 samples of input data - sample 1 will have 80% of total rows and
-        # sample 2 will have 20% of total rows.
-        iris_sample = iris_input.sample(frac=[0.8, 0.2])
-
-        # Create train dataset from sample 1 by filtering on "sampleid" and drop
-        # "sampleid" column as it is not required for training model.
-        iris_train = iris_sample[iris_sample.sampleid == "1"].drop("sampleid", axis = 1)
-
-        # Create test dataset from sample 2 by filtering on "sampleid" and
-        # drop "sampleid" column as it is not required for scoring.
-        iris_test = iris_sample[iris_sample.sampleid == "2"].drop("sampleid", axis = 1)
-
-        # Training the model.
-        XGBoost_out_2 = XGBoost(data=iris_train,
-                                input_columns=['sepal_length', 'sepal_width', 'petal_length', 'petal_width'],
-                                response_column = 'species',
-                                max_depth=3,
-                                lambda1 = 10000.0,
-                                model_type='Classification',
-                                seed=-1,
-                                shrinkage_factor=0.1,
-                                iter_num=2)
-
-        # XGBoostPredict() predicts the result using generated Classification model by
-        # XGBoost() and XGBoost object as input.
-        XGBoostPredict_out_2 = XGBoostPredict(newdata=iris_test,
-                                              object=XGBoost_out_2,
-                                              id_column='id',
-                                              model_type='Classification',
-                                              num_boosted_trees=3,
-                                              iter_num=2,
-                                              output_prob=True,
-                                              output_responses=['1', '2', '3'],
-                                              object_order_column=['task_index', 'tree_num', 'iter',
-                                                                   'class_num', 'tree_order'])
-
-        # Print the result DataFrame.
-        print(XGBoostPredict_out_2.result)
-    """
+def XGBoostPredict(newdata=None, object=None, id_column=None, num_boosted_tree=1000,
+                   iter_num=3, accumulate=None, output_prob=False, model_type="REGRESSION",
+                   output_responses=None, detailed=False, **generic_arguments):
+    """
+    DESCRIPTION:
+        The XGBoostPredict() function runs the predictive algorithm based on the model generated
+        by XGBoost(). The XGBoost() function, also known as eXtreme Gradient Boosting, performs
+        classification or regression analysis on datasets.
+
+        XGBoostPredict() performs prediction for test input data using multiple simple trees in
+        the trained model. The test input data should have the same attributes as used during
+        the training phase, which can be up to 2046. These attributes are used to score based
+        on the trees in the model.
+
+        The output contains prediction for each data point in the test data based on regression
+        or classification. The prediction probability is computed based on the majority vote
+        from participating trees. A higher probability implies a more confident prediction by
+        the model. Majority of the trees result in the same prediction.
+
+        Notes:
+            * The processing time is controlled by (proportional to):
+                * The number of boosted trees used for prediction from the model (controlled
+                  by "num_boosted_trees").
+                * The number of iterations (sub-trees) used for prediction from the model
+                  in each boosted tree (controlled by "iter_num").
+
+            A careful choice of these parameters can be used to control the processing time.
+            When the boosted trees size grows more than what can fit in memory, the trees are
+            cached in a local spool space, which may impact the performance of the function
+            compared to the case when all trees fit in memory.
+
+    PARAMETERS:
+        newdata:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the input data.
+            Types: teradataml DataFrame
+
+        object:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the model data generated by XGBoost()
+            function or the instance of XGBoost.
+            Types: teradataml DataFrame or XGBoost
+
+        id_column:
+            Required Argument.
+            Specifies the input data column name that contains a unique
+            identifier for each test point in the test set.
+            Note:
+                * Input column names with double quotation marks are not allowed for this function.
+            Types: str
+
+        num_boosted_tree:
+            Optional Argument.
+            Specifies how many boosted trees to use to make predictions.
+            A combination of both 'task_Index' and 'tree_num' in the model table determines
+            the AMPID and number of trees generated by that AMP. As we order the model table
+            with these two arguments, the number of boosted trees that are loaded are based
+            on this order.
+            For example, if there are two AMPs on the system and AMP 1 ('task_index': 0) generates
+            three boosted trees ('tree_num':1,2,3), while AMP 2 ('task_index': 1) generate two boosted
+            trees ('tree_num': 1,2). Then, "num_boosted_tree"(4) loads three boosted trees from AMP1
+            ('task_index': 0) and one boosted tree from AMP2 ('task_index': 1).
+            As one boosted tree is skipped altogether from loading it in memory and making predictions,
+            this results in a faster elapsed time for queries compared to loading all trees in memory.
+            However, this can also lead to loss in prediction accuracy. In addition, any unique tree
+            is determined by 'task_index', 'tree_id' and 'iter_num' in the model table.
+            Default Value: 1000
+            Types: int
+
+        iter_num:
+            Optional Argument.
+            Specifies how many iterations to load for each boosted tree to make predictions.
+            For example, AMP1 ('task_index':0) generates three boosted trees ('tree_num': 1,2,3)
+            with each tree having four iterations ('iter':1,2,3,4). There are 12 trees in total.
+            "iter_num"(2) only loads two iterations per boosted tree, that is, only six trees
+            are loaded for this example.
+            As some trees are skipped from being loaded in memory and predictions are made
+            without them, this results in a faster elapsed time for queries compared to
+            loading all trees in memory, but also lead to loss in prediction accuracy.
+            Default Value: 3
+            Types: int
+
+        accumulate:
+            Optional Argument.
+            Specifies the name(s) of input teradataml DataFrame column(s) to copy to the
+            output. By default, the function copies no input teradataml DataFrame columns
+            to the output.
+            Types: str OR list of Strings (str)
+
+        output_prob:
+            Optional Argument.
+            Specifies whether the function should output the probability for each
+            "output_responses".
+            Notes:
+                * If "output_prob" is true and "output_responses" are not provided,
+                  output the probability of the predicted class.
+                * The "output_prob" argument works only when "model_type" is
+                  'Classification'.
+            Default Value: False
+            Types: bool
+
+        model_type:
+            Optional Argument.
+            Specifies whether the analysis is a regression (continuous response variable) or
+            a multiple-class classification (predicting result from the number of classes).
+            For 'Classification', output the prediction column as integers. These integral
+            values represent different categories, and so are better observed as an integer
+            column. To make the output schema for prediction column as an integer, set
+            "model_type" as 'Classification'.
+            Permitted Values:
+                * Regression
+                * Classification
+            Default Value: Regression
+            Types: str
+
+        output_responses:
+            Optional Argument.
+            Specifies the classes for which to output probabilities.
+            Notes:
+                * If "output_prob" is true and "output_responses" are not provided,
+                  output the probability of the predicted class.
+                * The "output_responses" argument works only when "model_type" is
+                  'Classification'.
+            Types: str OR list of str(s)
+
+        detailed:
+            Optional Argument.
+            Specifies whether to output detailed information of each prediction.
+            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)
+                * "<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 SQLE Engine function supports, else an
+                exception is raised.
+
+    RETURNS:
+        Instance of XGBoostPredict.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as XGBoostPredictObj.<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.
+
+        # Load the example data.
+        load_example_data("teradataml", "titanic")
+        load_example_data("byom", "iris_input")
+
+        # Create teradataml DataFrame objects.
+        titanic = DataFrame.from_table("titanic")
+        iris_input = DataFrame("iris_input")
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Example 1: This example takes titanic data as input, and generates the Regression
+        #            model using XGBoost(). Using XGBoostPredict() function to predict the
+        #            fare with the Regression model generated by XGBoost().
+
+        # Create 2 samples of input data - sample 1 will have 80% of total rows and
+        # sample 2 will have 20% of total rows.
+        titanic_sample = titanic.sample(frac=[0.8, 0.2])
+
+        # Create train dataset from sample 1 by filtering on "sampleid" and drop
+        # "sampleid" column as it is not required for training model.
+        titanic_train = titanic_sample[titanic_sample.sampleid == "1"].drop("sampleid", axis = 1)
+
+        # Create test dataset from sample 2 by filtering on "sampleid" and
+        # drop "sampleid" column as it is not required for scoring.
+        titanic_test = titanic_sample[titanic_sample.sampleid == "2"].drop("sampleid", axis = 1)
+
+        XGBoost_out_1 = XGBoost(data=titanic_train,
+                                input_columns=["age", "survived", "pclass"],
+                                response_column = 'fare',
+                                max_depth=3,
+                                lambda1 = 1000.0,
+                                model_type='Regression',
+                                seed=-1,
+                                shrinkage_factor=0.1,
+                                iter_num=2)
+
+        # XGBoostPredict() predicts the result using generated Regression model by
+        # XGBoost() and "newdata".
+        XGBoostPredict_out_1 = XGBoostPredict(newdata=titanic_test,
+                                              object=XGBoost_out_1.result,
+                                              id_column='passenger',
+                                              object_order_column=['task_index', 'tree_num',
+                                                                   'iter', 'tree_order'])
+
+        # Print the result DataFrame.
+        print(XGBoostPredict_out_1.result)
+
+        # Example 2: This example takes titanic data, and generates the Classification
+        #            model using XGBoost(). Using XGBoostPredict() function to predict the fare
+        #            with the Classification model generated by XGBoost(). Provides the classes for
+        #            which to output the probabilities.
+
+        # Create 2 samples of input data - sample 1 will have 80% of total rows and
+        # sample 2 will have 20% of total rows.
+        iris_sample = iris_input.sample(frac=[0.8, 0.2])
+
+        # Create train dataset from sample 1 by filtering on "sampleid" and drop
+        # "sampleid" column as it is not required for training model.
+        iris_train = iris_sample[iris_sample.sampleid == "1"].drop("sampleid", axis = 1)
+
+        # Create test dataset from sample 2 by filtering on "sampleid" and
+        # drop "sampleid" column as it is not required for scoring.
+        iris_test = iris_sample[iris_sample.sampleid == "2"].drop("sampleid", axis = 1)
+
+        # Training the model.
+        XGBoost_out_2 = XGBoost(data=iris_train,
+                                input_columns=['sepal_length', 'sepal_width', 'petal_length', 'petal_width'],
+                                response_column = 'species',
+                                max_depth=3,
+                                lambda1 = 10000.0,
+                                model_type='Classification',
+                                seed=-1,
+                                shrinkage_factor=0.1,
+                                iter_num=2)
+
+        # XGBoostPredict() predicts the result using generated Classification model by
+        # XGBoost() and XGBoost object as input.
+        XGBoostPredict_out_2 = XGBoostPredict(newdata=iris_test,
+                                              object=XGBoost_out_2,
+                                              id_column='id',
+                                              model_type='Classification',
+                                              num_boosted_trees=3,
+                                              iter_num=2,
+                                              output_prob=True,
+                                              output_responses=['1', '2', '3'],
+                                              object_order_column=['task_index', 'tree_num', 'iter',
+                                                                   'class_num', 'tree_order'])
+
+        # Print the result DataFrame.
+        print(XGBoostPredict_out_2.result)
+    """