[mlpack-git] master: Update tutorial to discuss empty clusters and LloydStepType. (76c0fc6)

[gitdub at mlpack.org]

Repository : https://github.com/mlpack/mlpack
On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/8551a21f9821399ded164d8dbb11e453bcb33c45...e8e2ff17da5978cacf3c9a45d4aa572a4bf008e5

>---------------------------------------------------------------

commit 76c0fc62838e6db45df638475467ffaab2a2aa41
Author: Ryan Curtin <ryan at ratml.org>
Date:   Mon May 2 21:31:51 2016 +0000

    Update tutorial to discuss empty clusters and LloydStepType.


>---------------------------------------------------------------

76c0fc62838e6db45df638475467ffaab2a2aa41
 doc/tutorials/kmeans/kmeans.txt | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/tutorials/kmeans/kmeans.txt b/doc/tutorials/kmeans/kmeans.txt
index 1f54f96..c9f7e80 100644
--- a/doc/tutorials/kmeans/kmeans.txt
+++ b/doc/tutorials/kmeans/kmeans.txt
@@ -653,11 +653,13 @@ The \c LloydStepType policy also mandates three functions:
 @code
 /**
  * Run a single iteration of the Lloyd algorithm, updating the given centroids
- * into the newCentroids matrix.
+ * into the newCentroids matrix.  If any cluster is empty (that is, if any
+ * cluster has no points assigned to it), then the centroid associated with
+ * that cluster may be filled with invalid data (it will be corrected later).
  *
  * @param centroids Current cluster centroids.
  * @param newCentroids New cluster centroids.
- * @param counts Counts of the number of points in each cluster.
+ * @param counts Number of points in each cluster at the end of the iteration.
  */
 double Iterate(const arma::mat& centroids,
                arma::mat& newCentroids,
@@ -670,6 +672,10 @@ double Iterate(const arma::mat& centroids,
 size_t DistanceCalculations() const { return distanceCalculations; }
 @endcode
 
+Note that \c Iterate() does not need to return valid centroids if the cluster is
+empty.  This is because \c EmptyClusterPolicy will handle the empty centroid.
+This behavior can be used to avoid small amounts of computation.
+
 For examples, see the five aforementioned implementations of classes that
 satisfy the \c LloydStepType policy.