teradataml 20.0.0.8__py3-none-any.whl

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

@@ -0,0 +1,415 @@
+def GLMPerSegment(formula=None, data=None, input_columns=None, response_column=None,
+                  attribute_data=None, parameter_data=None, family="GAUSSIAN",
+                  iter_max=300, batch_size=10, lambda1=0.02, alpha=0.15,
+                  iter_num_no_change=50, tolerance=0.001, intercept=True,
+                  class_weights="0:1.0, 1:1.0", learning_rate=None, initial_eta=0.05,
+                  decay_rate=0.25, decay_steps=5, momentum=0.0, nesterov=True,
+                  iteration_mode="BATCH", partition_column=None, **generic_arguments):
+    """
+    DESCRIPTION:
+        The GLM() function is used to train the whole data set as one model. The
+        GLMPerSegment() function is a partition-by-key function to create a single
+        model for each partition.
+        The following operations are supported for GLMPerSegment():
+            * Gaussian linear regression.
+            * Binomial logistic regression for binary classification.
+            * Iteration modes batch and epoch.
+            * Regularization using L1, L2 and Elasticnet.
+            * Mini-batch gradient descent for numeric optimization algorithm.
+            * Training support with and without intercept.
+            * Class-weighted modeling.
+            * Learning rate support for mini-batch gradient descent using constant,
+              dynamic and hybrid gradients.
+            * Learning rate optimization algorithms for mini-batch gradient
+              descent using plain, momentum, and nesterov gradients.
+
+        Notes:
+            * The order column can be optionally applied to guarantee the result in each
+              run is deterministic. The situation of indeterministic result in a partition
+              can occur if the "batch_size" argument is less than the number of rows in
+              the partition. However, adding order columns can influence the performance.
+            * A model is generated from the GLMPerSegment(), and a model from GLM()
+              should be the same when the "batch_size" argument is not less than the
+              number of rows in the corresponding partition of the model.
+            * GLMPerSegment() takes all features as numeric input. Categorical columns
+              must be converted to numeric columns as preprocessing step, such as using
+              OneHotEncodingFit()/OneHotEncodingTransform(), OrdinalEncodingFit()/
+              OrdinalEncodingTransform(), and TargetEncodingFit()/TargetEncodingTransform().
+            * Any observation with a missing value in an input column is ignored and
+              not used fortraining. You can use some imputation function, such as
+              SimpleImputeFit()/SimpleImputeTransform() to do imputation of missing values.
+            * Best practice is to standardize the dataset before using GLMPerSegment().
+              Standardization, also known as feature scaling, makes a better model and
+              converges quicker.
+            * Model evaluation metrics of MSE, Loglikelihood, AIC, and BIC are generated by
+              GLMPerSegment(). For additional regression and classification metrics, you
+              should use RegressionEvaluator(), ClassificationEvaluator() and ROC()
+              functions as post-processing step.
+            * GLMPerSegment() supports binary classification only.
+            * "response_column" for classification accepts values of 0 and 1 for two
+              classes in the response column.
+            * A maximum of 2046 features are supported due to the limitation imposed
+              by the maximum number of columns (2048) in a input data.
+            * "batch_size" and "learning_rate" are directly related. With a larger "batch_size",
+               "learning_rate" can be increased for faster training with fewer iterations.
+            * "iter_num" and "iter_num_no_change" are criteria used to stop learning. To force
+               the function to run through all iterations, disable the "iter_num_no_change"
+               by specifying "iter_num_no_change" to 0.
+            * User need to try different combinations to find the best values for a particular
+              use case.
+            * When an unsupported data type is passed in "input_columns" or "response_column",
+              the error message is of the following format:
+              Unsupported data type for column index n in argument InputColumns.
+              In the message, n refers to the index of the column based on an input to the
+              function comprising "input_columns" and "response_column only. This is due to
+              the rest of the columns in input are not needed by the function and internal
+              optimizer does not expose them to the function. Due to this, n might be different
+              from the actual index in the input data.
+
+    PARAMETERS:
+        formula:
+            Required Argument when "input_columns" and "response_column" are not
+            provided, optional otherwise.
+            Specifies a string consisting of "formula" which is the model to be fitted.
+            Only basic formula of the "col1 ~ col2 + col3 +..." form are
+            supported and all variables must be from the same teradataml
+            DataFrame object.
+            Notes:
+                * The function only accepts numeric features. User must convert the
+                  categorical features to numeric values, before passing to the formula.
+                * In case categorical features are passed to formula, those are ignored,
+                  and only numeric features are considered.
+                * Provide either "formula" argument or "input_columns" and
+                  "response_column" arguments.
+            Types: str
+
+        data:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the input data.
+            Types: teradataml DataFrame
+
+        attribute_data:
+            Optional Argument.
+            Specifies the teradataml DataFrame containing a subset of features
+            to be used with respect to each partition.
+            Types: teradataml DataFrame
+
+        parameter_data:
+            Optional Argument.
+            Specifies the teradataml DataFrame containing a subset of parameters
+            to be used with respect to each partition.
+            Types: teradataml DataFrame
+
+        input_columns:
+            Required argument when "response_column" is provided and "formula" is not
+            provided, optional otherwise.
+            Specifies the name(s) of the teradataml DataFrame column(s) that need
+            to be used for training the model (predictors, features, or
+            independent variables).
+            Types: str OR list of Strings (str)
+
+        response_column:
+            Required argument when "response_column" is provided and "formula" is not
+            provided, optional otherwise.
+            Specifies the name of the column that contains the class label for binary
+            classification when "family" is 'Binomial', or target value (dependent
+            variable) for 'Regression' when "family" is 'Gaussian'.
+            Types: str
+
+        family:
+            Optional Argument.
+            Specifies the distribution exponential family.
+            Permitted Values:
+                * BINOMIAL
+                * GAUSSIAN
+            Default Value: GAUSSIAN
+            Types: str
+
+        iter_max:
+            Optional Argument.
+            Specifies the maximum number of iterations over the training data
+            batches. If batch size is 0, then "iter_max" equals the number of epochs.
+            Note:
+                * The "iter_max" must be in the range [1, 10000000].
+            Default Value: 300
+            Types: int
+
+        batch_size:
+            Optional Argument.
+            Specifies the number of observations (training samples) to be parsed in
+            one mini-batch. Must be a non-negative integer value. A value of 0
+            indicates no mini-batches, so the entire input is processed in each
+            iteration, and the algorithm becomes (Batch) Gradient Descent. A
+            value higher than the number of rows on any partition also default
+            to Batch Gradient Descent.
+            Note:
+                * The "iter_max" must be in the range [0, 2147483647].
+            Default Value: 10
+            Types: int
+
+        lambda1:
+            Optional Argument.
+            Specifies the amount of regularization to be added. The higher the
+            value, the stronger the regularization. It is also used to compute
+            learning rate when "learning_rate" is set to 'Optimal'.
+            A value of '0' means no regularization.
+            Notes:
+                * The "lambda1" must be in the range [0, 1e7].
+                * The "lambda1" must be a non-negative float value.
+            Default Value: 0.02
+            Types: float OR int
+
+        alpha:
+            Optional Argument.
+            Specifies the Elasticnet parameter for penalty computation. It is
+            only effective if "lambda1" is greater than 0. The value represents
+            the contribution ratio of L1 in the penalty. A value of 1.0 indicates
+            L1 (LASSO) only, a value of 0 indicates L2 (Ridge) only, and a value
+            in between is a combination of L1 and L2.
+            Note:
+                * The "alpha" must be in the range [0, 1].
+            Default Value: 0.15
+            Types: float OR int
+
+        iter_num_no_change:
+            Optional Argument.
+            Specifies the number of iterations with no improvement in loss, including
+            the "tolerance", to stop training. A value of 0 indicates no early
+            stopping and the algorithm continues until "iter_max" iterations are reached.
+            Note:
+                * The "iter_num_no_change" must be in the range [0, 2147483647].
+            Default Value: 50
+            Types: int
+
+        tolerance:
+            Optional Argument.
+            Specifies the stopping criteria in terms of loss function improvement.
+            Training stops when loss is greater than best_loss – tolerance for
+            "iter_num_no_change" times.
+            Notes:
+                * The "tolerance" must be in the range [1e-7, 1e7].
+                * The "tolerance" works only when "iter_num_no_change"
+                  is greater than 0.
+                * The "tolerance" must be a non-negative value.
+            Default Value: 0.001
+            Types: float OR int
+
+        intercept:
+            Optional Argument.
+            Specifies intercept should be estimated based on whether data is
+            already centered or not.
+            Default Value: True
+            Types: bool
+
+        class_weights:
+            Optional Argument.
+            Specifies the weights associated with classes. The format is
+            '0:weight,1:weight'. For example, '0:1.0,1:0.5' gives twice
+            as much weight to each observation in class 0. If the weight of
+            a class is omitted, then it is assumed to be 1.0.
+            Note:
+                * The "class_weights" argument works only when "family" is
+                  'Binomial'.
+            Default Value: 0:1.0, 1:1.0
+            Types: str
+
+        learning_rate:
+            Optional Argument.
+            Specifies the Learning rate algorithm.
+            Permitted Values:
+                * CONSTANT
+                * OPTIMAL
+                * INVTIME
+                * ADAPTIVE
+            Default Value:
+                * 'INVTIME' when "family" is set to 'Gaussian'
+                * 'OPTIMAL' when "family" is set to 'Binomial'
+            Types: str
+
+        initial_eta:
+            Optional Argument.
+            Specifies the initial value of eta for learning rate. For constant,
+            this value is the learning rate for all iterations.
+            Note:
+                * The "initial_eta" must be in the range [1e-7, 1e7].
+            Default Value: 0.05.
+            Types: float OR int
+
+        decay_rate:
+            Optional Argument.
+            Specifies the decay rate for learning rate (invtime and adaptive).
+            Note:
+                * The "decay_rate" must be in the range [1e-7, 1e7].
+            Default Value: 0.25.
+            Types: float OR int
+
+        decay_steps:
+            Optional Argument.
+            Specifies the decay steps (number of iterations) for adaptive learning rate.
+            The learning rate changes by decay rate after this many number of iterations.
+            Note:
+                * The "decay_steps" must be in the range [1, 2147483647].
+            Default Value: 5
+            Types: int
+
+        momentum:
+            Optional Argument.
+            Specifies the value to use for momentum learning rate optimizer.
+            A larger value indicates higher momentum contribution. A value of 0
+            means momentum optimizer is disabled. For a good momentum contribution,
+            a value between 0.6-0.95 is recommended.
+            Note:
+                * The "momentum" must be in the range [0, 1].
+            Default Value: 0.0
+            Types: float OR int
+
+        nesterov:
+            Optional Argument.
+            Specifies the indicator that nesterov optimization should be
+            applied to Momentum Optimizer or not. Default is True when momentum
+            is greater than 0, otherwise False.
+            Default Value: True
+            Types: bool
+
+        iteration_mode:
+            Optional Argument.
+            Specifies the iteration mode.
+            Permitted Values:
+                * Batch: One iteration per batch. After processing rows in a
+                  batch, update the weight of the parameters and proceed to the
+                   next iteration.
+                * Epoch: One iteration per epoch. After processing all rows
+                  in a partition (with one or more batches), update the weight
+                  of the parameters and proceed to the next epoch.
+            Default Value: Batch
+            Types: str OR list of Strings (str)
+
+        partition_column:
+            Optional Argument.
+            Specifies the name of the "input_columns" on which to partition the input.
+            The name should be consistent with the "data_partition_column". If the
+            "data_partition_column" is unicode with foreign language characters, then
+            it is necessary to specify "partition_column" argument.
+            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)
+                * "<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 GLMPerSegment.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as GLMPerSegmentObj.<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("decisionforestpredict", ["housing_train"])
+        load_example_data("teradataml", ["housing_train_attribute", "housing_train_parameter"])
+
+        # Create teradataml DataFrame objects.
+        housing_train = DataFrame.from_table("housing_train")
+        housing_train_attribute = DataFrame.from_table("housing_train_attribute")
+        housing_train_parameter = DataFrame.from_table("housing_train_parameter")
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Filter the rows from train dataset with homestyle as Classic and Eclectic.
+        binomial_housing_train = DataFrame('housing_train', index_label="homestyle")
+        binomial_housing_train = binomial_housing_train.filter(like = 'ic', axis = 'rows')
+
+        # GLMPerSegment() function requires features in numeric format for processing,
+        # so dropping the non-numeric columns.
+        binomial_housing_train = binomial_housing_train.drop(columns=["driveway", "recroom",
+                                                                      "gashw", "airco", "prefarea",
+                                                                      "fullbase"])
+        gaussian_housing_train = binomial_housing_train.drop(columns="homestyle")
+
+        # Transform the train dataset categorical values to encoded values.
+        housing_train_ordinal_encodingfit = OrdinalEncodingFit(
+            target_column='homestyle',
+            data=binomial_housing_train)
+
+        housing_train_ordinal_encodingtransform = OrdinalEncodingTransform(
+            data=binomial_housing_train,
+            object=housing_train_ordinal_encodingfit.result,
+            accumulate=["sn", "price", "lotsize",
+                        "bedrooms", "bathrms", "stories"])
+
+        # Example 1: Train the model using the 'Gaussian' family.
+        GLMPerSegment_out_1 = GLMPerSegment(data=gaussian_housing_train,
+                                            data_partition_column="stories",
+                                            input_columns=['garagepl', 'lotsize', 'bedrooms', 'bathrms'],
+                                            response_column="price",
+                                            family="Gaussian",
+                                            iter_max=1000,
+                                            batch_size=9)
+
+        # Print the result DataFrame.
+        print(GLMPerSegment_out_1.result)
+
+        # Example 2: Train the model using the 'Binomial' family, formula argument and
+        #            subset of features and parameters to be used with respect to
+        #            "partition_id".
+        formula = "homestyle ~ price + lotsize + bedrooms + bathrms"
+        GLMPerSegment_out_2 = GLMPerSegment(data=housing_train_ordinal_encodingtransform.result,
+                                            data_partition_column="stories",
+                                            formula = formula,
+                                            attribute_data=housing_train_attribute,
+                                            attribute_data_partition_column="partition_id",
+                                            parameter_data=housing_train_parameter,
+                                            parameter_data_partition_column="partition_id",
+                                            family="Binomial",
+                                            iter_max=100)
+
+        # Print the result DataFrame.
+        print(GLMPerSegment_out_2.result)
+    """

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

@@ -0,0 +1,144 @@
+def GLMPredict(modeldata = None, newdata = None, terms = None, family = None, linkfunction = "CANONICAL",
+               output_prob = False, output_responses = None, **generic_arguments):
+    
+    """
+    DESCRIPTION:
+    The GLMPredict() function uses the model generated by the function GLM()
+    to perform generalized linear model prediction on new input data.
+
+    Note:
+        * The GLMPredict() function accepts models from the GLM() function in MLE,
+          whereas the TDGLMPredict() function accepts models from GLM() function in SQLE.
+
+
+    PARAMETERS:
+        modeldata:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the model data
+            generated by GLM() function or an instance of GLM.
+            Types: teradataml DataFrame or GLM
+
+        newdata:
+            Required Argument.
+            Specifies the teradataml DataFrame containing the input data.
+            Types: teradataml DataFrame
+
+        terms:
+            Optional Argument.
+            Specifies the names of newdata columns to copy to the output
+            teradataml DataFrame.
+            Types: str OR list of Strings (str)
+
+        family:
+            Optional Argument.
+            Specifies the distribution exponential family. The default value is
+            read from modeldata. If you specify this argument, you must give it
+            the same value that you used for the Family argument of the function
+            when you generated the model.
+            Permitted Values: LOGISTIC, BINOMIAL, POISSON, GAUSSIAN, GAMMA,
+            INVERSE_GAUSSIAN, NEGATIVE_BINOMIAL
+            Types: str
+
+        linkfunction:
+            Optional Argument.
+            The canonical link functions (default link functions) and the link
+            functions that are allowed for each exponential family.
+            Note:
+                Use the same value that you used for the Link argument of the
+                function  when you generated the model.
+            Default Value: "CANONICAL"
+            Permitted Values: CANONICAL, IDENTITY, INVERSE, LOG,
+            COMPLEMENTARY_LOG_LOG, SQUARE_ROOT, INVERSE_MU_SQUARED, LOGIT,
+            PROBIT, CAUCHIT
+            Types: str
+
+        output_prob:
+            Optional Argument.
+            Specifies whether to output probabilities.
+            Default Value: False
+            Types: bool
+
+        output_responses:
+            Optional Argument.
+            Specifies responses for which to output probabilities.
+            Types: str OR list of strs
+
+        **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: boolean
+
+                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: boolean
+
+            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 SQL Engine
+                function supports, else an exception is raised.
+
+    RETURNS:
+        Instance of GLMPredict.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as GLMPredictObj.<attribute_name>.
+        Output teradataml DataFrame attribute name is:
+            result
+
+
+    RAISES:
+        TeradataMlException
+
+
+    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 data to run the example.
+        load_example_data("GLMPredict", "admissions_test")
+        load_example_data("teradataml", "glm_admissions_model")
+
+        # Create teradataml DataFrame objects.
+        admissions_test = DataFrame.from_table("admissions_test")
+
+        # Create teradataml DataFrame object for model data.
+        glm_admissions_model = DataFrame.from_table("glm_admissions_model")
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Example 1: Predicting if student is admitted or not with probabilities of
+        #            the both the responses. Response '1' means admitted and '0' means
+        #            not admitted.
+        obj = teradataml.GLMPredict(modeldata = glm_admissions_model,
+                                    newdata = admissions_test,
+                                    newdata_order_column="id",
+                                    modeldata_order_column=["attribute", "predictor"],
+                                    family="LOGISTIC",
+                                    terms=["id", "masters", "gpa", "stats", "programming", "admitted"],
+                                    linkfunction="CANONICAL",
+                                    output_prob=True,
+                                    output_responses=["1", "0"])
+
+        # Print the result DataFrame.
+        print(obj.result)
+
+    """