001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.math4.ml.clustering;
019
020import java.util.List;
021
022/**
023 * Defines a measure of the quality of clusters.
024 */
025public interface ClusterEvaluator {
026    /**
027     * @param cList List of clusters.
028     * @return the score attributed by the evaluator.
029     */
030    double score(List<? extends Cluster<? extends Clusterable>> cList);
031
032    /**
033     * Provides a means to interpret the {@link #score(List) score value}.
034     *
035     * @param a Score computed by this evaluator.
036     * @param b Score computed by this evaluator.
037     * @return {@code true} if the evaluator considers that score
038     * {@code a} is better than score {@code b}.
039     */
040    boolean isBetterScore(double a, double b);
041
042    /**
043     * Converts to a {@link ClusterRanking ranking function}
044     * (as required by clustering implementations).
045     *
046     * @param <T> the type of points that can be clustered
047     * @param eval Evaluator function.
048     * @return a ranking function.
049     */
050    static <T extends Clusterable> ClusterRanking ranking(ClusterEvaluator eval) {
051        return eval.isBetterScore(1, 2) ?
052            clusters -> 1 / eval.score(clusters) :
053            clusters -> eval.score(clusters);
054    }
055}