ClusterEvaluator.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.math4.legacy.ml.clustering;

  18. import java.util.List;

  19. /**
  20.  * Defines a measure of the quality of clusters.
  21.  */
  22. public interface ClusterEvaluator {
  23.     /**
  24.      * @param cList List of clusters.
  25.      * @return the score attributed by the evaluator.
  26.      */
  27.     double score(List<? extends Cluster<? extends Clusterable>> cList);

  28.     /**
  29.      * Provides a means to interpret the {@link #score(List) score value}.
  30.      *
  31.      * @param a Score computed by this evaluator.
  32.      * @param b Score computed by this evaluator.
  33.      * @return {@code true} if the evaluator considers that score
  34.      * {@code a} is better than score {@code b}.
  35.      */
  36.     boolean isBetterScore(double a, double b);

  37.     /**
  38.      * Converts to a {@link ClusterRanking ranking function}
  39.      * (as required by clustering implementations).
  40.      *
  41.      * @param <T> the type of points that can be clustered
  42.      * @param eval Evaluator function.
  43.      * @return a ranking function.
  44.      */
  45.     static <T extends Clusterable> ClusterRanking ranking(ClusterEvaluator eval) {
  46.         return eval.isBetterScore(1, 2) ?
  47.             clusters -> 1 / eval.score(clusters) :
  48.             clusters -> eval.score(clusters);
  49.     }
  50. }