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

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

@@ -1,204 +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,
-           **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.
-            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
-
-        **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")
-
-        # Create teradataml DataFrame objects.
-        computers_train1 = DataFrame.from_table("computers_train1")
-
-        # 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_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)
-
-    """
+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) 
+
+    """