Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[MATH-898] Add implementation of fuzzy k-means clusterer. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1466247 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2013-04-09 21:28:36 +00:00
parent fda2af9247
commit 4b8647bf6c
1 changed files with 382 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

382
src/main/java/org/apache/commons/math3/ml/clustering/FuzzyKMeansClusterer.java Normal file
View File

@ -0,0 +1,382 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.math3.ml.clustering;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import org.apache.commons.math3.exception.MathIllegalArgumentException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.linear.MatrixUtils;
import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.ml.distance.DistanceMeasure;
import org.apache.commons.math3.ml.distance.EuclideanDistance;
import org.apache.commons.math3.random.JDKRandomGenerator;
import org.apache.commons.math3.random.RandomGenerator;
import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.util.MathArrays;
import org.apache.commons.math3.util.MathUtils;
/**
* Fuzzy K-Means algorithm.
* <p>
* TODO
* <p>
* The algorithm requires two parameters:
* <ul>
* <li>k: the number of clusters
* <li>fuzzyness: ...
* </ul>
*
* @param <T> type of the points to cluster
* @version $Id$
* @since 4.0
*/
public class FuzzyKMeansClusterer<T extends Clusterable> extends Clusterer<T> {
/** The default value for the convergence criteria. */
private static final double DEFAULT_EPSILON = 1e-3;
/** The number of clusters. */
private final int k;
/** The maximum number of iterations. */
private final int maxIterations;
/** The fuzzyness factor. */
private final double fuzzyness;
/** The convergence criteria. */
private final double epsilon;
/** Random generator for choosing initial centers. */
private final RandomGenerator random;
/** The membership matrix. */
private double[][] membershipMatrix;
/** The list of points used in the last call to {@link #cluster(Collection)}. */
private List<T> points;
/** The list of clusters resulting from the last call to {@link #cluster(Collection)}. */
private List<CentroidCluster<T>> clusters;
/**
* Creates a new instance of a FuzzyKMeansClusterer.
* <p>
* The euclidean distance will be used as default distance measure.
*
* @param k the number of clusters to split the data into
* @param fuzzyness the fuzzyness factor, must be &gt; 1.0
* @throws NumberIsTooSmallException if {@code fuzzyness <= 1.0}
*/
public FuzzyKMeansClusterer(final int k, final double fuzzyness) throws NumberIsTooSmallException {
this(k, fuzzyness, -1, new EuclideanDistance());
}
/**
* Creates a new instance of a FuzzyKMeansClusterer.
*
* @param k the number of clusters to split the data into
* @param fuzzyness the fuzzyness factor, must be &gt; 1.0
* @param maxIterations the maximum number of iterations to run the algorithm for.
* If negative, no maximum will be used.
* @param measure the distance measure to use
* @throws NumberIsTooSmallException if {@code fuzzyness <= 1.0}
*/
public FuzzyKMeansClusterer(final int k, final double fuzzyness,
final int maxIterations, final DistanceMeasure measure)
throws NumberIsTooSmallException {
this(k, fuzzyness, maxIterations, measure, DEFAULT_EPSILON, new JDKRandomGenerator());
}
/**
* Creates a new instance of a FuzzyKMeansClusterer.
*
* @param k the number of clusters to split the data into
* @param fuzzyness the fuzzyness factor, must be &gt; 1.0
* @param maxIterations the maximum number of iterations to run the algorithm for.
* If negative, no maximum will be used.
* @param measure the distance measure to use
* @param epsilon the convergence criteria
* @param random random generator to use for choosing initial centers
* @throws NumberIsTooSmallException if {@code fuzzyness <= 1.0}
*/
public FuzzyKMeansClusterer(final int k, final double fuzzyness,
final int maxIterations, final DistanceMeasure measure,
final double epsilon, final RandomGenerator random)
throws NumberIsTooSmallException {
super(measure);
if (fuzzyness <= 1.0d) {
throw new NumberIsTooSmallException(fuzzyness, 1.0, false);
}
this.k = k;
this.fuzzyness = fuzzyness;
this.maxIterations = maxIterations;
this.epsilon = epsilon;
this.random = random;
this.membershipMatrix = null;
this.points = null;
this.clusters = null;
}
/**
* Return the number of clusters this instance will use.
* @return the number of clusters
*/
public int getK() {
return k;
}
/**
* Returns the fuzzyness factor used by this instance.
* @return the fuzzyness factor
*/
public double getFuzzyness() {
return fuzzyness;
}
/**
* Returns the maximum number of iterations this instance will use.
* @return the maximum number of iterations, or -1 if no maximum is set
*/
public int getMaxIterations() {
return maxIterations;
}
/**
* Returns the random generator this instance will use.
* @return the random generator
*/
public RandomGenerator getRandomGenerator() {
return random;
}
/**
* Returns the {@code nxk} membership matrix, where {@code n} is the number
* of data points and {@code k} the number of clusters.
* <p>
* The element U<sub>i,j</sub> represents the membership value for data point {@code i}
* to cluster {@code j}.
*
* @return the membership matrix
*/
public RealMatrix getMembershipMatrix() {
return MatrixUtils.createRealMatrix(membershipMatrix);
}
/**
* Returns an unmodifiable list of the data points used in the last
* call to {@link #cluster(Collection)}.
* @return the list of data points, or {@code null} if {@link #cluster(Collection)} has
* not been called before.
*/
public List<T> getDataPoints() {
return points;
}
/**
* Returns the list of clusters resulting from the last call to {@link #cluster(Collection)}.
* @return the list of clusters, or {@code null} if {@link #cluster(Collection)} has
* not been called before.
*/
public List<CentroidCluster<T>> getClusters() {
return clusters;
}
/**
* Get the value of the objective function.
* @return the objective function as double value, or {@code 0.0} if {@link #cluster(Collection)}
* has not been called before.
*/
public double getObjectiveFunctionValue() {
if (points == null || clusters == null) {
return 0;
}
int i = 0;
double objFunction = 0.0;
for (final T point : points) {
int j = 0;
for (final CentroidCluster<T> cluster : clusters) {
double dist = distance(point, cluster.getCenter());
objFunction += (dist * dist) * FastMath.pow(membershipMatrix[i][j], fuzzyness);
j++;
}
i++;
}
return objFunction;
}
/**
* Performs Fuzzy K-Means cluster analysis.
*
* @param dataPoints the points to cluster
* @return the list of clusters
* @throws MathIllegalArgumentException if the data points are null or the number
* of clusters is larger than the number of data points
*/
public List<CentroidCluster<T>> cluster(final Collection<T> dataPoints)
throws MathIllegalArgumentException {
// sanity checks
MathUtils.checkNotNull(dataPoints);
final int size = dataPoints.size();
// number of clusters has to be smaller or equal the number of data points
if (size < k) {
throw new NumberIsTooSmallException(size, k, false);
}
// copy the input collection to an unmodifiable list with indexed access
points = Collections.unmodifiableList(new ArrayList<T>(dataPoints));
clusters = new ArrayList<CentroidCluster<T>>();
membershipMatrix = new double[size][k];
final double[][] oldMatrix = new double[size][k];
// if no points are provided, return an empty list of clusters
if (size == 0) {
return clusters;
}
initializeMembershipMatrix();
// there is at least one point
final int pointDimension = points.get(0).getPoint().length;
for (int i = 0; i < k; i++) {
clusters.add(new CentroidCluster<T>(new DoublePoint(new double[pointDimension])));
}
int iteration = 0;
final int max = (maxIterations < 0) ? Integer.MAX_VALUE : maxIterations;
double difference = 0.0;
do {
saveMembershipMatrix(oldMatrix);
updateClusterCenters();
updateMembershipMatrix();
difference = calculateMaxMembershipChange(oldMatrix);
} while (difference > epsilon && ++iteration < max);
return clusters;
}
/**
* Update the cluster centers.
*/
private void updateClusterCenters() {
int j = 0;
final List<CentroidCluster<T>> newClusters = new ArrayList<CentroidCluster<T>>(k);
for (final CentroidCluster<T> cluster : clusters) {
final Clusterable center = cluster.getCenter();
int i = 0;
double[] arr = new double[center.getPoint().length];
double sum = 0.0;
for (final T point : points) {
final double u = FastMath.pow(membershipMatrix[i][j], fuzzyness);
final double[] pointArr = point.getPoint();
for (int idx = 0; idx < arr.length; idx++) {
arr[idx] += u * pointArr[idx];
}
sum += u;
i++;
}
MathArrays.scaleInPlace(1.0 / sum, arr);
newClusters.add(new CentroidCluster<T>(new DoublePoint(arr)));
j++;
}
clusters.clear();
clusters = newClusters;
}
/**
* Updates the membership matrix and assigns the points to the cluster with
* the highest membership.
*/
private void updateMembershipMatrix() {
for (int i = 0; i < points.size(); i++) {
final T point = points.get(i);
double maxMembership = 0.0;
int newCluster = -1;
for (int j = 0; j < clusters.size(); j++) {
double sum = 0.0;
final double distA = FastMath.abs(distance(point, clusters.get(j).getCenter()));
for (final CentroidCluster<T> c : clusters) {
final double distB = FastMath.abs(distance(point, c.getCenter()));
sum += FastMath.pow(distA / distB, 2.0 / (fuzzyness - 1.0));
}
membershipMatrix[i][j] = 1.0 / sum;
if (membershipMatrix[i][j] > maxMembership) {
maxMembership = membershipMatrix[i][j];
newCluster = j;
}
}
clusters.get(newCluster).addPoint(point);
}
}
/**
* Initialize the membership matrix with random values.
*/
private void initializeMembershipMatrix() {
for (int i = 0; i < points.size(); i++) {
for (int j = 0; j < k; j++) {
membershipMatrix[i][j] = random.nextDouble();
}
membershipMatrix[i] = MathArrays.normalizeArray(membershipMatrix[i], 1.0);
}
}
/**
* Calculate the maximum element-by-element change of the membership matrix
* for the current iteration.
*
* @param matrix the membership matrix of the previous iteration
* @return the maximum membership matrix change
*/
private double calculateMaxMembershipChange(final double[][] matrix) {
double maxMembership = 0.0;
for (int i = 0; i < points.size(); i++) {
for (int j = 0; j < clusters.size(); j++) {
double v = FastMath.abs(membershipMatrix[i][j] - matrix[i][j]);
maxMembership = FastMath.max(v, maxMembership);
}
}
return maxMembership;
}
/**
* Copy the membership matrix into the provided matrix.
*
* @param matrix the place to store the membership matrix
*/
private void saveMembershipMatrix(final double[][] matrix) {
for (int i = 0; i < points.size(); i++) {
System.arraycopy(membershipMatrix[i], 0, matrix[i], 0, clusters.size());
}
}
}