[SPARK-13672][ML] Add python examples of BisectingKMeans in ML and MLLIB

JIRA: https://issues.apache.org/jira/browse/SPARK-13672

## What changes were proposed in this pull request?

add two python examples of BisectingKMeans for ml and mllib

## How was this patch tested?

manual tests

Author: Zheng RuiFeng <ruifengz@foxmail.com>

Closes #11515 from zhengruifeng/mllib_bkm_pe.

4 files changed, 114 insertions, 0 deletions

diff --git a/docs/mllib-clustering.md b/docs/mllib-clustering.md
index 44720147be..6897ba4a5d 100644
--- a/docs/mllib-clustering.md
+++ b/docs/mllib-clustering.md
@@ -399,6 +399,12 @@ Refer to the [`BisectingKMeans` Java docs](api/java/org/apache/spark/mllib/clust
 
 {% include_example java/org/apache/spark/examples/mllib/JavaBisectingKMeansExample.java %}
 </div>
+
+<div data-lang="python" markdown="1">
+Refer to the [`BisectingKMeans` Python docs](api/python/pyspark.mllib.html#pyspark.mllib.clustering.BisectingKMeans) and [`BisectingKMeansModel` Python docs](api/python/pyspark.mllib.html#pyspark.mllib.clustering.BisectingKMeansModel) for more details on the API.
+
+{% include_example python/mllib/bisecting_k_means_example.py %}
+</div>
 </div>
 
 ## Streaming k-means
diff --git a/examples/src/main/python/ml/bisecting_k_means_example.py b/examples/src/main/python/ml/bisecting_k_means_example.py
new file mode 100644
index 0000000000..e6f6bfd7e8
--- /dev/null
+++ b/examples/src/main/python/ml/bisecting_k_means_example.py
@@ -0,0 +1,57 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from __future__ import print_function
+
+from pyspark import SparkContext
+# $example on$
+from pyspark.ml.clustering import BisectingKMeans, BisectingKMeansModel
+from pyspark.mllib.linalg import VectorUDT, _convert_to_vector, Vectors
+from pyspark.mllib.linalg import Vectors
+from pyspark.sql.types import Row
+# $example off$
+from pyspark.sql import SQLContext
+
+"""
+A simple example demonstrating a bisecting k-means clustering.
+"""
+
+if __name__ == "__main__":
+
+    sc = SparkContext(appName="PythonBisectingKMeansExample")
+    sqlContext = SQLContext(sc)
+
+    # $example on$
+    data = sc.textFile("data/mllib/kmeans_data.txt")
+    parsed = data.map(lambda l: Row(features=Vectors.dense([float(x) for x in l.split(' ')])))
+    training = sqlContext.createDataFrame(parsed)
+
+    kmeans = BisectingKMeans().setK(2).setSeed(1).setFeaturesCol("features")
+
+    model = kmeans.fit(training)
+
+    # Evaluate clustering
+    cost = model.computeCost(training)
+    print("Bisecting K-means Cost = " + str(cost))
+
+    centers = model.clusterCenters()
+    print("Cluster Centers: ")
+    for center in centers:
+        print(center)
+    # $example off$
+
+    sc.stop()
diff --git a/examples/src/main/python/mllib/bisecting_k_means_example.py b/examples/src/main/python/mllib/bisecting_k_means_example.py
new file mode 100644
index 0000000000..7f4d0402d6
--- /dev/null
+++ b/examples/src/main/python/mllib/bisecting_k_means_example.py
@@ -0,0 +1,50 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from __future__ import print_function
+
+# $example on$
+from numpy import array
+# $example off$
+
+from pyspark import SparkContext
+# $example on$
+from pyspark.mllib.clustering import BisectingKMeans, BisectingKMeansModel
+# $example off$
+
+if __name__ == "__main__":
+    sc = SparkContext(appName="PythonBisectingKMeansExample")  # SparkContext
+
+    # $example on$
+    # Load and parse the data
+    data = sc.textFile("data/mllib/kmeans_data.txt")
+    parsedData = data.map(lambda line: array([float(x) for x in line.split(' ')]))
+
+    # Build the model (cluster the data)
+    model = BisectingKMeans.train(parsedData, 2, maxIterations=5)
+
+    # Evaluate clustering
+    cost = model.computeCost(parsedData)
+    print("Bisecting K-means Cost = " + str(cost))
+
+    # Save and load model
+    path = "target/org/apache/spark/PythonBisectingKMeansExample/BisectingKMeansModel"
+    model.save(sc, path)
+    sameModel = BisectingKMeansModel.load(sc, path)
+    # $example off$
+
+    sc.stop()
diff --git a/python/pyspark/mllib/clustering.py b/python/pyspark/mllib/clustering.py
index 5a5bf59dd5..23d118bd40 100644
--- a/python/pyspark/mllib/clustering.py
+++ b/python/pyspark/mllib/clustering.py
@@ -142,6 +142,7 @@ class BisectingKMeans(object):
     .. versionadded:: 2.0.0
     """
 
+    @classmethod
     @since('2.0.0')
     def train(self, rdd, k=4, maxIterations=20, minDivisibleClusterSize=1.0, seed=-1888008604):
         """