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 19 import java.util.Collection; 20 import java.util.List; 21 22 import org.apache.commons.math4.legacy.ml.distance.DistanceMeasure; 23 24 /** 25 * Base class for clustering algorithms. 26 * 27 * @param <T> the type of points that can be clustered 28 * @since 3.2 29 */ 30 public abstract class Clusterer<T extends Clusterable> { 31 32 /** The distance measure to use. */ 33 private DistanceMeasure measure; 34 35 /** 36 * Build a new clusterer with the given {@link DistanceMeasure}. 37 * 38 * @param measure the distance measure to use 39 */ 40 protected Clusterer(final DistanceMeasure measure) { 41 this.measure = measure; 42 } 43 44 /** 45 * Perform a cluster analysis on the given set of {@link Clusterable} instances. 46 * 47 * @param points the set of {@link Clusterable} instances 48 * @return a {@link List} of clusters 49 * @throws IllegalArgumentException if points are null or the number of 50 * data points is not compatible with this clusterer. 51 * @throws org.apache.commons.math4.legacy.exception.ConvergenceException 52 * if the algorithm has not yet converged after the maximum number of 53 * iterations has been exceeded. 54 */ 55 public abstract List<? extends Cluster<T>> cluster(Collection<T> points); 56 57 /** 58 * Returns the {@link DistanceMeasure} instance used by this clusterer. 59 * 60 * @return the distance measure 61 */ 62 public DistanceMeasure getDistanceMeasure() { 63 return measure; 64 } 65 66 /** 67 * Calculates the distance between two {@link Clusterable} instances 68 * with the configured {@link DistanceMeasure}. 69 * 70 * @param p1 the first clusterable 71 * @param p2 the second clusterable 72 * @return the distance between the two clusterables 73 */ 74 protected double distance(final Clusterable p1, final Clusterable p2) { 75 return measure.compute(p1.getPoint(), p2.getPoint()); 76 } 77 }