From 68f7eae071e9cbc55069e09730bb17434d64dec1 Mon Sep 17 00:00:00 2001
From: Gilles <gilleseran@gmail.com>
Date: Tue, 10 Mar 2020 03:31:51 +0100
Subject: [PATCH] MATH-1516: Require that evaluators implement
 "ClusterEvaluator".

---
 src/changes/changes.xml                         |  3 +++
 .../clustering/evaluation/CalinskiHarabasz.java | 17 +++++++++++------
 .../ml/clustering/evaluation/package-info.java  |  4 ++++
 .../evaluation/CalinskiHarabaszTest.java        |  8 ++++----
 4 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index a3e1ceb66..e81b7eb44 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -54,6 +54,9 @@ If the output is not quite correct, check for invisible trailing spaces!
     </release>
 
     <release version="4.0" date="XXXX-XX-XX" description="">
+      <action dev="erans" type="add" issue="MATH-1519" due-to="Chentao">
+        Add "Calinski-Harabsz" clustering evaluator.
+      </action>
       <action dev="erans" type="update" issue="MATH-1523">
         Abstract class "ClusterEvaluator" replaced by an interface.
       </action>
diff --git a/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabasz.java b/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabasz.java
index 31145beca..0a0918cfe 100644
--- a/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabasz.java
+++ b/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabasz.java
@@ -19,7 +19,7 @@ package org.apache.commons.math4.ml.clustering.evaluation;
 
 import org.apache.commons.math4.exception.InsufficientDataException;
 import org.apache.commons.math4.ml.clustering.Cluster;
-import org.apache.commons.math4.ml.clustering.ClusterRanking;
+import org.apache.commons.math4.ml.clustering.ClusterEvaluator;
 import org.apache.commons.math4.ml.clustering.Clusterable;
 import org.apache.commons.math4.util.MathArrays;
 
@@ -38,12 +38,10 @@ import java.util.List;
  * @see <a href="https://www.tandfonline.com/doi/abs/10.1080/03610927408827101">A dendrite method for cluster
  * analysis</a>
  */
-public class CalinskiHarabasz<T extends Clusterable> implements ClusterRanking<T> {
-    /**
-     * {@inheritDoc}
-     */
+public class CalinskiHarabasz<T extends Clusterable> implements ClusterEvaluator<T> {
+    /** {@inheritDoc} */
     @Override
-    public double compute(List<? extends Cluster<T>> clusters) {
+    public double score(List<? extends Cluster<T>> clusters) {
         final int dimension = dimensionOfClusters(clusters);
         final double[] centroid = meanOfClusters(clusters, dimension);
 
@@ -68,6 +66,13 @@ public class CalinskiHarabasz<T extends Clusterable> implements ClusterRanking<T
                         (intraDistanceProduct * (clusterCount - 1)));
     }
 
+    /** {@inheritDoc} */
+    @Override
+    public boolean isBetterScore(double a,
+                                 double b) {
+        return a > b;
+    }
+
     /**
      * Calculate covariance of two double array.
      * <pre>
diff --git a/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/package-info.java b/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/package-info.java
index 2d02358cb..0631115d0 100644
--- a/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/package-info.java
+++ b/src/main/java/org/apache/commons/math4/ml/clustering/evaluation/package-info.java
@@ -16,5 +16,9 @@
  */
 /**
  * Cluster evaluation methods.
+ *
+ * All evaluators should implement the
+ * {@link org.apache.commons.math4.ml.clustering.ClusterEvaluator}
+ * interface.
  */
 package org.apache.commons.math4.ml.clustering.evaluation;
diff --git a/src/test/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabaszTest.java b/src/test/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabaszTest.java
index 3ed17549f..2ee5b0609 100644
--- a/src/test/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabaszTest.java
+++ b/src/test/java/org/apache/commons/math4/ml/clustering/evaluation/CalinskiHarabaszTest.java
@@ -18,7 +18,7 @@
 package org.apache.commons.math4.ml.clustering.evaluation;
 
 import org.apache.commons.math4.ml.clustering.CentroidCluster;
-import org.apache.commons.math4.ml.clustering.ClusterRanking;
+import org.apache.commons.math4.ml.clustering.ClusterEvaluator;
 import org.apache.commons.math4.ml.clustering.DoublePoint;
 import org.apache.commons.math4.ml.clustering.KMeansPlusPlusClusterer;
 import org.apache.commons.math4.ml.distance.DistanceMeasure;
@@ -33,7 +33,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 public class CalinskiHarabaszTest {
-    private ClusterRanking<DoublePoint> evaluator;
+    private ClusterEvaluator<DoublePoint> evaluator;
     private DistanceMeasure distanceMeasure;
 
     @Before
@@ -65,7 +65,7 @@ public class CalinskiHarabaszTest {
             final int k = i + 2;
             KMeansPlusPlusClusterer<DoublePoint> kMeans = new KMeansPlusPlusClusterer<>(k, -1, distanceMeasure, rnd);
             List<CentroidCluster<DoublePoint>> clusters = kMeans.cluster(points);
-            double score = evaluator.compute(clusters);
+            double score = evaluator.score(clusters);
             if (score > expectBestScore) {
                 expectBestScore = score;
             }
@@ -91,7 +91,7 @@ public class CalinskiHarabaszTest {
             final int k = i + 2;
             KMeansPlusPlusClusterer<DoublePoint> kMeans = new KMeansPlusPlusClusterer<>(k, -1, distanceMeasure, rnd);
             List<CentroidCluster<DoublePoint>> clusters = kMeans.cluster(points);
-            double score = evaluator.compute(clusters);
+            double score = evaluator.score(clusters);
             if (score > expectBestScore) {
                 expectBestScore = score;
             }