Top Description Fields Constructors Methods
org.apache.commons.math3.ml.clustering

public Class FuzzyKMeansClusterer<T extends Clusterable>

extends Clusterer<T extends Clusterable>
Class Inheritance
Type Parameters
<T>
type of the points to cluster
Imports
java.util.ArrayList, .Collection, .Collections, .List, org.apache.commons.math3.exception.MathIllegalArgumentException, .MathIllegalStateException, .NumberIsTooSmallException, org.apache.commons.math3.linear.MatrixUtils, .RealMatrix, org.apache.commons.math3.ml.distance.DistanceMeasure, .EuclideanDistance, org.apache.commons.math3.random.JDKRandomGenerator, .RandomGenerator, org.apache.commons.math3.util.FastMath, .MathArrays, .MathUtils
Fuzzy K-Means clustering algorithm.

The Fuzzy K-Means algorithm is a variation of the classical K-Means algorithm, with the major difference that a single data point is not uniquely assigned to a single cluster. Instead, each point i has a set of weights uij which indicate the degree of membership to the cluster j.

The algorithm then tries to minimize the objective function: 

J = ∑i=1..C∑k=1..N uikmdik2
with dik being the distance between data point i and the cluster center k.

The algorithm requires two parameters:

Additional, optional parameters:

The fuzzy variant of the K-Means algorithm is more robust with regard to the selection of the initial cluster centers.

Since
3.3

Field Summary

Modifier and TypeField and Description
private List<CentroidCluster<T>>
clusters

The list of clusters resulting from the last call to cluster(Collection).

private static final double
DEFAULT_EPSILON

The default value for the convergence criteria.

private final double
epsilon

The convergence criteria.

private final double
fuzziness

The fuzziness factor.

private final int
k

The number of clusters.

private final int
maxIterations

The maximum number of iterations.

private double[][]
membershipMatrix

The membership matrix.

private List<T>
points

The list of points used in the last call to cluster(Collection).

private final RandomGenerator
random

Random generator for choosing initial centers.

Constructor Summary

AccessConstructor and Description
public
FuzzyKMeansClusterer(final int
the number of clusters to split the data into
k, final double
the fuzziness factor, must be > 1.0
fuzziness)

Creates a new instance of a FuzzyKMeansClusterer.

public
FuzzyKMeansClusterer(final int
the number of clusters to split the data into
k, final double
the fuzziness factor, must be > 1.0
fuzziness, final int
the maximum number of iterations to run the algorithm for. If negative, no maximum will be used.
maxIterations, final DistanceMeasure
the distance measure to use
measure)

Creates a new instance of a FuzzyKMeansClusterer.

public
FuzzyKMeansClusterer(final int
the number of clusters to split the data into
k, final double
the fuzziness factor, must be > 1.0
fuzziness, final int
the maximum number of iterations to run the algorithm for. If negative, no maximum will be used.
maxIterations, final DistanceMeasure
the distance measure to use
measure, final double
the convergence criteria (default is 1e-3)
epsilon, final RandomGenerator
random generator to use for choosing initial centers
random)

Creates a new instance of a FuzzyKMeansClusterer.

Method Summary

Modifier and TypeMethod and Description
private double

Returns:

the maximum membership matrix change
calculateMaxMembershipChange(final double[][]
the membership matrix of the previous iteration
matrix)

Calculate the maximum element-by-element change of the membership matrix for the current iteration.

public List<CentroidCluster<T>>

Returns:

the list of clusters
cluster(final Collection<T>
the points to cluster
dataPoints)

Implements abstract org.apache.commons.math3.ml.clustering.Clusterer.cluster.

Performs Fuzzy K-Means cluster analysis.

public List<CentroidCluster<T>>

Returns:

the list of clusters, or null if cluster(Collection) has not been called before.
getClusters()

Returns the list of clusters resulting from the last call to cluster(Collection).

public List<T>

Returns:

the list of data points, or null if cluster(Collection) has not been called before.
getDataPoints()

Returns an unmodifiable list of the data points used in the last call to cluster(Collection).

public double

Returns:

the convergence criteria
getEpsilon()

Returns the convergence criteria used by this instance.

public double

Returns:

the fuzziness factor
getFuzziness()

Returns the fuzziness factor used by this instance.

public int

Returns:

the number of clusters
getK()

Return the number of clusters this instance will use.

public int

Returns:

the maximum number of iterations, or -1 if no maximum is set
getMaxIterations()

Returns the maximum number of iterations this instance will use.

public RealMatrix

Returns:

the membership matrix
getMembershipMatrix()

Returns the nxk membership matrix, where n is the number of data points and k the number of clusters.

public double

Returns:

the objective function evaluation as double value
getObjectiveFunctionValue()

Get the value of the objective function.

public RandomGenerator

Returns:

the random generator
getRandomGenerator()

Returns the random generator this instance will use.

private void
initializeMembershipMatrix()

Initialize the membership matrix with random values.

private void
saveMembershipMatrix(final double[][]
the place to store the membership matrix
matrix)

Copy the membership matrix into the provided matrix.

private void
updateClusterCenters()

Update the cluster centers.

private void
updateMembershipMatrix()

Updates the membership matrix and assigns the points to the cluster with the highest membership.

Inherited from org.apache.commons.math3.ml.clustering.Clusterer:
distancegetDistanceMeasure

Field Detail

clustersback to summary
private List<CentroidCluster<T>> clusters

The list of clusters resulting from the last call to cluster(Collection).

DEFAULT_EPSILONback to summary
private static final double DEFAULT_EPSILON

The default value for the convergence criteria.

epsilonback to summary
private final double epsilon

The convergence criteria.

fuzzinessback to summary
private final double fuzziness

The fuzziness factor.

kback to summary
private final int k

The number of clusters.

maxIterationsback to summary
private final int maxIterations

The maximum number of iterations.

membershipMatrixback to summary
private double[][] membershipMatrix

The membership matrix.

pointsback to summary
private List<T> points

The list of points used in the last call to cluster(Collection).

randomback to summary
private final RandomGenerator random

Random generator for choosing initial centers.

Constructor Detail

FuzzyKMeansClustererback to summary
public FuzzyKMeansClusterer(final int k, final double fuzziness) throws NumberIsTooSmallException

Creates a new instance of a FuzzyKMeansClusterer.

The euclidean distance will be used as default distance measure.

Parameters
k:int

the number of clusters to split the data into

fuzziness:double

the fuzziness factor, must be > 1.0

Exceptions
NumberIsTooSmallException:
if fuzziness <= 1.0
FuzzyKMeansClustererback to summary
public FuzzyKMeansClusterer(final int k, final double fuzziness, final int maxIterations, final DistanceMeasure measure) throws NumberIsTooSmallException

Creates a new instance of a FuzzyKMeansClusterer.

Parameters
k:int

the number of clusters to split the data into

fuzziness:double

the fuzziness factor, must be > 1.0

maxIterations:int

the maximum number of iterations to run the algorithm for. If negative, no maximum will be used.

measure:DistanceMeasure

the distance measure to use

Exceptions
NumberIsTooSmallException:
if fuzziness <= 1.0
FuzzyKMeansClustererback to summary
public FuzzyKMeansClusterer(final int k, final double fuzziness, final int maxIterations, final DistanceMeasure measure, final double epsilon, final RandomGenerator random) throws NumberIsTooSmallException

Creates a new instance of a FuzzyKMeansClusterer.

Parameters
k:int

the number of clusters to split the data into

fuzziness:double

the fuzziness factor, must be > 1.0

maxIterations:int

the maximum number of iterations to run the algorithm for. If negative, no maximum will be used.

measure:DistanceMeasure

the distance measure to use

epsilon:double

the convergence criteria (default is 1e-3)

random:RandomGenerator

random generator to use for choosing initial centers

Exceptions
NumberIsTooSmallException:
if fuzziness <= 1.0

Method Detail

calculateMaxMembershipChangeback to summary
private double calculateMaxMembershipChange(final double[][] matrix)

Calculate the maximum element-by-element change of the membership matrix for the current iteration.

Parameters
matrix:double[][]

the membership matrix of the previous iteration

Returns:double

the maximum membership matrix change

clusterback to summary
public List<CentroidCluster<T>> cluster(final Collection<T> dataPoints) throws MathIllegalArgumentException

Implements abstract org.apache.commons.math3.ml.clustering.Clusterer.cluster.

Performs Fuzzy K-Means cluster analysis.

Parameters
dataPoints:Collection<T>

the points to cluster

Returns:List<CentroidCluster<T>>

the list of clusters

Annotations
@Override
Exceptions
MathIllegalArgumentException:
if the data points are null or the number of clusters is larger than the number of data points
getClustersback to summary
public List<CentroidCluster<T>> getClusters()

Returns the list of clusters resulting from the last call to cluster(Collection).

Returns:List<CentroidCluster<T>>

the list of clusters, or null if cluster(Collection) has not been called before.

getDataPointsback to summary
public List<T> getDataPoints()

Returns an unmodifiable list of the data points used in the last call to cluster(Collection).

Returns:List<T>

the list of data points, or null if cluster(Collection) has not been called before.

getEpsilonback to summary
public double getEpsilon()

Returns the convergence criteria used by this instance.

Returns:double

the convergence criteria

getFuzzinessback to summary
public double getFuzziness()

Returns the fuzziness factor used by this instance.

Returns:double

the fuzziness factor

getKback to summary
public int getK()

Return the number of clusters this instance will use.

Returns:int

the number of clusters

getMaxIterationsback to summary
public int getMaxIterations()

Returns the maximum number of iterations this instance will use.

Returns:int

the maximum number of iterations, or -1 if no maximum is set

getMembershipMatrixback to summary
public RealMatrix getMembershipMatrix()

Returns the nxk membership matrix, where n is the number of data points and k the number of clusters.

The element Ui,j represents the membership value for data point i to cluster j.

Returns:RealMatrix

the membership matrix

Exceptions
MathIllegalStateException:
if cluster(Collection) has not been called before
getObjectiveFunctionValueback to summary
public double getObjectiveFunctionValue()

Get the value of the objective function.

Returns:double

the objective function evaluation as double value

Exceptions
MathIllegalStateException:
if cluster(Collection) has not been called before
getRandomGeneratorback to summary
public RandomGenerator getRandomGenerator()

Returns the random generator this instance will use.

Returns:RandomGenerator

the random generator

initializeMembershipMatrixback to summary
private void initializeMembershipMatrix()

Initialize the membership matrix with random values.

saveMembershipMatrixback to summary
private void saveMembershipMatrix(final double[][] matrix)

Copy the membership matrix into the provided matrix.

Parameters
matrix:double[][]

the place to store the membership matrix

updateClusterCentersback to summary
private void updateClusterCenters()

Update the cluster centers.

updateMembershipMatrixback to summary
private void updateMembershipMatrix()

Updates the membership matrix and assigns the points to the cluster with the highest membership.