teradataml 20.0.0.8__py3-none-any.whl

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

@@ -0,0 +1,224 @@
+def Histogram(data=None, object=None, target_columns=None, method_type=None, nbins=1, inclusion="LEFT",
+              groupby_columns=None, **generic_arguments):
+    """
+    DESCRIPTION:
+        The Histogram() function calculates the frequency distribution of a data set
+        using any of these methods:
+            * Sturges
+            * Scott
+            * Variable-width
+            * Equal-width
+
+        Notes:
+            * This function requires the UTF8 client character set for UNICODE data.
+            * This function does not support Pass Through Characters (PTCs).
+            * This function does not support KanjiSJIS or Graphic data types.
+
+
+    PARAMETERS:
+        data:
+            Required Argument.
+            Specifies the input teradataml DataFrame.
+            Types: teradataml DataFrame
+
+        object:
+            Required when "method_type" is 'VARIABLE-WIDTH', optional otherwise.
+            Specifies the bin data.
+            Types: teradataml DataFrame
+
+        target_columns:
+            Required Argument.
+            Specifies the name(s) of the column(s) in "data" to perform computations on.
+            Types: str OR list of Strings (str)
+
+        method_type:
+            Required Argument.
+            Specifies the method type to be used for histogram computation.
+            Permitted Values:
+                * STURGES -
+                    Algorithm for calculating bin width, w:
+                         w = r/(1 + log\u2082 n)
+                         where:
+                             w = bin width
+                             r = data value range
+                             n = number of elements in data set
+                         Sturges algorithm performs best if data is normally distributed
+                         and n is at least 30.
+
+                * SCOTT -
+                    Algorithm for calculating bin width, w:
+                         w = 3.49s/(n^1/3)
+                         where:
+                             w = bin width
+                             s = standard deviation of data values
+                             n = number of elements in data set
+                             r = data value range
+                             Number of bins: r/w
+                         Scott algorithm performs best on normally distributed data.
+
+                * VARIABLE-WIDTH -
+                    Requires "object" argument, which specifies the minimum value and the
+                    maximum value of the bin.
+                    When one target column is specified, specify the minimum value
+                    in column1 in "object" data , maximum value in column2 in "object"
+                    data, and label of the bin in column3.
+                    When more than one target column is specified, specify the
+                    column name present in "target_column" attribute in column1
+                    in "object" data, minimum value in column2 in "object" data,
+                    maximum value in column3 in "object" data, and the label of
+                    the bin in column4 in "object" data.
+                    Note:
+                        * The maximum number of bins cannot exceed 10000 per column.
+
+                * EQUAL-WIDTH -
+                    Algorithm for calculating bin width, w:
+                    w = (max - min)/k
+                    where:
+                        min = minimum value of the bins
+                        max = maximum value of the bins
+                        k = number of intervals into which algorithm divides data set
+                        Interval boundaries: min+w, min+2w, …, min+(k-1)w
+                    "object" argument is optional.
+                    When "object" data is omitted, Histogram() function internally computes
+                    the min value and max value from the input data for the target columns.
+                    When "object" data is specified, the user can specify in the following
+                    manner:
+                        * When one target column is specified, specify min value in column1
+                          in "object" data and max value in column2 in "object" data.
+                        * When more than one target column is specified, specify the
+                          column name present in "target_column" attribute in column1
+                          in "object" data, min value in column2 in "object" data,
+                          and max value in column3 in "object" data.
+            Types: str
+
+        nbins:
+            Required when "method_type" is 'VARIABLE-WIDTH' and 'EQUAL-WIDTH',
+            optional otherwise.
+            Specifies the number of bins.
+            Notes:
+                * When only one value is specified, it is applied to all the target columns.
+                  Otherwise, the number of "nbins" values must be equal to the number of
+                  target columns.
+                * The maximum "nbins" value is 10000.
+            Default Value: 1
+            Types: int OR list of ints
+
+        inclusion:
+            Optional Argument.
+            Specifies whether points on bin boundaries should be included in the
+            bin on the left or the right.
+            Note:
+                * When only one value is specified, it is applied to all the target columns.
+                  Otherwise, the number of "inclusion" values must be equal to the number
+                  of target columns.
+            Default Value: "LEFT"
+            Permitted Values: LEFT, RIGHT
+            Types: str OR list of Strings (str)
+
+        groupby_columns:
+            Optional Argument.
+            Specifies the names of the input data columns that contain the group
+            values for binning.
+            Notes:
+                * This argument must not have columns that are already specified
+                  in "target_columns".
+                * This argument does not support range.
+                * The maximum number of unique columns in the "groupby_columns"
+                  argument is 2042.
+            Types: str OR list of Strings (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: 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 Histogram.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as HistogramObj.<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", "min_max_titanic"])
+
+        # Create teradataml DataFrame object.
+        titanic_data = DataFrame.from_table("titanic")
+
+        # Create teradataml DataFrame object for minimum and maximum value of bins
+        # "Young age", "Middle Age" and, "Old Age".
+        min_max_object = DataFrame.from_table("min_max_titanic")
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Example 1: Get the frequency distribution of a data set using 'STURGES'
+        #            method type for the values in column 'age'.
+        obj1 = Histogram(data=titanic_data,
+                         target_columns="age",
+                         method_type="STURGES")
+
+        # Print the result DataFrame.
+        print(obj1.result)
+
+        # Example 2: Get the frequency distribution of a data set using 'VARIABLE-WIDTH'
+        #            method type for the values in column 'age' with 3 number of bins.
+        obj2 = Histogram(data=titanic_data,
+                         object=min_max_object,
+                         target_columns="age",
+                         method_type="VARIABLE-WIDTH",
+                         nbins=3)
+
+        # Print the result DataFrame.
+        print(obj2.result)
+
+        # Example 3: Get the frequency distribution of a data set with respect
+        #            to 'sex' column using 'EQUAL-WIDTH' method type for the
+        #            values in column 'age' and 'fare' with 3 and 2 number
+        #            of bins respectively.
+        obj3 = Histogram(data=titanic_data,
+                         target_columns=["age", "fare"],
+                         method_type="EQUAL-WIDTH",
+                         nbins=[3,2],
+                         groupby_columns=["sex"])
+
+        # Print the result DataFrame.
+        print(obj3.result)
+    """

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

@@ -0,0 +1,251 @@
+def KMeans(data=None, centroids_data=None, id_column=None, target_columns=None, num_clusters=None,
+           seed=None, threshold=0.0395, iter_max=10, num_init=1, output_cluster_assignment=False,
+           initialcentroids_method="RANDOM", **generic_arguments):
+    """
+    DESCRIPTION:
+        The K-means() function groups a set of observations into k clusters
+        in which each observation belongs to the cluster with the nearest mean
+        (cluster centers or cluster centroid). This algorithm minimizes the
+        objective function, that is, the total Euclidean distance of all data points
+        from the center of the cluster as follows:
+            1. Specify or randomly select k initial cluster centroids.
+            2. Assign each data point to the cluster that has the closest centroid.
+            3. Recalculate the positions of the k centroids.
+            4. Repeat steps 2 and 3 until the centroids no longer move.
+        The algorithm doesn't necessarily find the optimal configuration as it
+        depends significantly on the initial randomly selected cluster centers.
+        User can run the function multiple times to reduce the effect of this limitation.
+
+        Also, this function returns the within-cluster-squared-sum, which user can use to
+        determine an optimal number of clusters using the Elbow method.
+        Notes:
+            * This function doesn't consider the "data" and "centroids_data"
+              input rows that have a NULL entry in the specified "target_columns".
+            * The function can produce deterministic output across different machine
+              configurations if user provide the "centroids_data".
+            * The function randomly samples the initial centroids from the "data",
+              if "centroids_data" not provided. In this case, use of "seed"
+              argument makes the function output deterministic on a machine with an
+              assigned configuration. However, using the "seed" argument won't guarantee
+              deterministic output across machines with different configurations.
+            * This function requires the UTF8 client character set for UNICODE data.
+            * This function does not support Pass Through Characters (PTCs).
+            * For information about PTCs, see Teradata Vantage™ - Analytics Database
+              International Character Set Support.
+            * This function does not support KanjiSJIS or Graphic data types.
+
+
+    PARAMETERS:
+        data:
+            Required Argument.
+            Specifies the input teradataml DataFrame.
+            Types: teradataml DataFrame
+
+        centroids_data:
+            Optional Argument.
+            Specifies the input teradataml DataFrame containing
+            set of initial centroids.
+            Note:
+                * This argument is not required if "num_clusters" provided.
+                * If provided, the function uses the initial centroids
+                  from this input.
+            Types: teradataml DataFrame
+
+        id_column:
+            Required Argument.
+            Specifies the input data column name that has the
+            unique identifier for each row in the input.
+            Types: str
+
+        target_columns:
+            Required Argument.
+            Specifies the name(s) of the column(s) in "data" for clustering.
+            Types: str OR list of Strings (str)
+
+        num_clusters:
+            Optional Argument.
+            Specifies the number of clusters to be created.
+            Note:
+                This argument is not required if "centroids_data" provided.
+            Types: int
+
+        seed:
+            Optional Argument.
+            Specifies a non-negative integer value to randomly select the initial
+            cluster centroid positions from the input.
+            Note:
+                * This argument is not required if "centroids_data" provided.
+                * Random integer value will be used for "seed", if not passed.
+            Types: int
+
+        threshold:
+            Optional Argument.
+            Specifies the convergence threshold. The algorithm converges if the distance
+            between the centroids from the previous iteration and the current iteration
+            is less than the specified value.
+            Default Value: 0.0395
+            Types: float OR int
+
+        iter_max:
+            Optional Argument.
+            Specifies the maximum number of iterations for the K-means algorithm.
+            The algorithm stops after performing the specified number of iterations
+            even if the convergence criterion is not met.
+            Default Value: 10
+            Types: int
+
+        num_init:
+            Optional Argument.
+            Specifies the number of times, the k-means algorithm will be run with different
+            initial centroid seeds. The function will emit out the model having
+            the least value of Total Within Cluster Squared Sum.
+            Note:
+                This argument is not required if "centroids_data" is provided.
+            Default Value: 1
+            Types: int
+
+        output_cluster_assignment:
+            Optional Argument.
+            Specifies whether to output Cluster Assignment information.
+            Default Value: False
+            Types: bool
+        
+        initialcentroids_method:
+            Optional Argument.
+            Specifies the initialization method to be used for selecting initial set of centroids.
+            Permitted Values: 'RANDOM', 'KMEANS++'
+            Default Value: 'RANDOM'
+            Note:
+                * This argument is not required if "centroids_data" is provided.
+            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 SQL Engine function supports, else an
+                exception is raised.
+
+    RETURNS:
+        Instance of KMeans.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as KMeansObj.<attribute_name>.
+        Output teradataml DataFrame attribute names are:
+            1. result
+            2. model_data
+
+
+    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("kmeans", "computers_train1")
+        load_example_data("kmeans",'kmeans_table')
+
+        # Create teradataml DataFrame objects.
+        computers_train1 = DataFrame.from_table("computers_train1")
+        kmeans_tab = DataFrame('kmeans_table')
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Example 1 : Grouping a set of observations into 2 clusters in which
+        #             each observation belongs to the cluster with the nearest mean.
+        KMeans_out = KMeans(id_column="id",
+                            target_columns=['price', 'speed'],
+                            data=computers_train1,
+                            num_clusters=2)
+
+        # Print the result DataFrames.
+        print(KMeans_out.result)
+        print(KMeans_out.model_data)
+
+        # Example 2 : Grouping a set of observations by specifying initial
+        #             centroid data.
+
+        # Get the set of initial centroids by accessing the group of rows
+        # from input data.
+        kmeans_initial_centroids_table = computers_train1.loc[[19, 97]]
+        kmeans_initial_centroids = kmeans_tab.loc[[2, 4]]
+
+        KMeans_out_1 = KMeans(id_column="id",
+                              target_columns=['price', 'speed'],
+                              data=computers_train1,
+                              centroids_data=kmeans_initial_centroids_table)
+
+        # Print the result DataFrames.
+        print(KMeans_out_1.result)
+        print(KMeans_out_1.model_data)
+
+        # Example 3 : Grouping a set of observations into 2 clusters by
+        #             specifying the number of clusters and seed value
+        #             with output cluster assignment information.
+        obj = KMeans(data=kmeans_tab,
+             id_column='id',
+             target_columns=['c1', 'c2'],
+             threshold=0.0395,
+             iter_max=3,
+             centroids_data=kmeans_initial_centroids,
+             output_cluster_assignment=True
+            )
+             
+        # Print the result DataFrames.
+        print(obj.result)
+
+        # Example 4 : Grouping a set of observations into 3 clusters by
+        #             specifying the number of clusters for initial centroids
+        #             method as KMEANS++.
+        obj = KMeans(data=kmeans_tab,
+             id_column='id',
+             target_columns=['c1', 'c2'],
+             threshold=0.0395,
+             iter_max=3,
+             num_clusters=3,
+             output_cluster_assignment=True,
+             initialcentroids_method="KMEANS++"
+            )
+        
+        # Print the result DataFrames.
+        print(obj.result) 
+
+    """

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

@@ -0,0 +1,144 @@
+def KMeansPredict(data=None, object=None, accumulate=None, output_distance=False, **generic_arguments):
+    """
+    DESCRIPTION:
+        The KMeansPredict() function uses the cluster centroids in
+        the KMeans() function output to assign the input data points
+        to the cluster centroids.
+
+        Notes:
+            * This function requires the UTF8 client character
+              set for UNICODE data.
+            * This function does not support Pass Through
+              Characters (PTCs).
+            * For information about PTCs, see Teradata Vantage™ -
+              Analytics Database International Character Set Support.
+            * This function does not support KanjiSJIS or Graphic data types.
+
+
+    PARAMETERS:
+        data:
+            Required Argument.
+            Specifies the input teradataml DataFrame.
+            Types: teradataml DataFrame
+
+        object:
+            Required Argument.
+            Specifies the teradataml DataFrame generated by
+            KMeans() function or the instance of KMeans.
+            Types: teradataml DataFrame or KMeans
+
+        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_distance:
+            Optional Argument.
+            Specifies whether to return the distance between
+            each data point and the nearest cluster.
+            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 SQL Engine function supports, else an
+                exception is raised.
+
+    RETURNS:
+        Instance of KMeansPredict.
+        Output teradataml DataFrames can be accessed using attribute
+        references, such as KMeansPredictObj.<attribute_name>.
+        Output teradataml DataFrame attribute name is:
+            1. 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("kmeans", "computers_train1")
+
+        # Create teradataml DataFrame objects.
+        computers_train1 = DataFrame.from_table("computers_train1")
+
+        # Check the list of available analytic functions.
+        display_analytic_functions()
+
+        # Grouping a set of observations into 2 clusters in which
+        # each observation belongs to the cluster with the nearest mean.
+        KMeans_out = KMeans(id_column="id",
+                            target_columns=['price', 'speed'],
+                            data=computers_train1,
+                            num_clusters=2)
+
+        # Print the result DataFrames.
+        print(KMeans_out.result)
+        print(KMeans_out.model_data)
+
+        # Example 1 : Assign the input data points to the cluster centroid
+        #             using the model generated by the KMeans() function.
+        #             Note that teradataml DataFrame representing the model
+        #             is passed as input to "object".
+        KMeansPredict_out = KMeansPredict(data=computers_train1,
+                                         object=KMeans_out.result
+                                         )
+
+        # Print the result DataFrames.
+        print(KMeansPredict_out.result)
+
+        # Example 2 : Assign the input data points to the cluster centroid
+        #             using the model generated by the KMeans() function.
+        #             Note that model is passed as instance of KMeans to "object".
+        KMeansPredict_out_1 = KMeansPredict(data=computers_train1,
+                                            object=KMeans_out,
+                                            accumulate="ram",
+                                            output_distance=False)
+
+        # Print the result DataFrames.
+        print(KMeansPredict_out_1.result)
+
+    """