[mlpack] 38/149: Comment the Rules class a little better.

[Barak A. Pearlmutter]

This is an automated email from the git hooks/post-receive script.

bap pushed a commit to branch svn-trunk
in repository mlpack.

commit b93441427a1470bf31b45ac9660d4bcf5f26cc20
Author: rcurtin <rcurtin at 9d5b8971-822b-0410-80eb-d18c1038ef23>
Date:   Sun Oct 12 20:50:50 2014 +0000

    Comment the Rules class a little better.
    
    
    git-svn-id: http://svn.cc.gatech.edu/fastlab/mlpack/trunk@17246 9d5b8971-822b-0410-80eb-d18c1038ef23
---
 .../methods/kmeans/pelleg_moore_kmeans_rules.hpp   | 45 ++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/src/mlpack/methods/kmeans/pelleg_moore_kmeans_rules.hpp b/src/mlpack/methods/kmeans/pelleg_moore_kmeans_rules.hpp
index c4fc419..998e65b 100644
--- a/src/mlpack/methods/kmeans/pelleg_moore_kmeans_rules.hpp
+++ b/src/mlpack/methods/kmeans/pelleg_moore_kmeans_rules.hpp
@@ -14,20 +14,65 @@
 namespace mlpack {
 namespace kmeans {
 
+/**
+ * The rules class for the single-tree Pelleg-Moore kd-tree traversal for
+ * k-means clustering.  Although TreeType is a free template parameter, this
+ * particular implementation is specialized to trees with hyper-rectangle bounds
+ * due to the pruning rule used to determine if one cluster dominates a node
+ * with respect to another cluster.
+ *
+ * Our implementation here abuses the single-tree algorithm abstractions a
+ * little bit.  Instead of doing a traversal for a particular query point, in
+ * this case we consider all clusters at once---so the query point is entirely
+ * ignored during in BaseCase() and Score().
+ */
 template<typename MetricType, typename TreeType>
 class PellegMooreKMeansRules
 {
  public:
+  /**
+   * Create the PellegMooreKMeansRules object.
+   *
+   * @param dataset The dataset that the tree is built on.
+   * @param centroids The current centroids.
+   * @param newCentroids New centroids after this iteration (output).
+   * @param counts Current cluster counts, to be replaced with new cluster
+   *      counts.
+   * @param metric Instantiated metric.
+   */
   PellegMooreKMeansRules(const typename TreeType::Mat& dataset,
                          const arma::mat& centroids,
                          arma::mat& newCentroids,
                          arma::Col<size_t>& counts,
                          MetricType& metric);
 
+  /**
+   * The BaseCase() function for this single-tree algorithm does nothing.
+   * Instead, point-to-cluster comparisons are handled as necessary in Score().
+   *
+   * @param queryIndex Index of query point (fake, will be ignored).
+   * @param referenceIndex Index of reference point.
+   */
   double BaseCase(const size_t queryIndex, const size_t referenceIndex);
 
+  /**
+   * Determine if a cluster can be pruned, and if not, perform point-to-cluster
+   * comparisons.  The point-to-cluster comparisons are performed here and not
+   * in BaseCase() because of the complexity of managing the blacklist.
+   *
+   * @param queryIndex Index of query point (fake, will be ignored).
+   * @param referenceNode Node containing points in the dataset.
+   */
   double Score(const size_t queryIndex, TreeType& referenceNode);
 
+  /**
+   * Rescore to determine if a node can be pruned.  In this case, a node can
+   * never be pruned during rescoring, so this just returns oldScore.
+   *
+   * @param queryIndex Index of query point (fake, will be ignored).
+   * @param referenceNode Node containing points in the dataset.
+   * @param oldScore Resulting score from Score().
+   */
   double Rescore(const size_t queryIndex,
                  TreeType& referenceNode,
                  const double oldScore);

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/mlpack.git