public class DoubleKMeans extends Object implements SpatialClusterer<DoubleCentroidsResult,double[]>
DoubleNearestNeighbours
; for
example, approximate KMeans can be achieved using a
DoubleNearestNeighboursKDTree
whilst exact KMeans can be achieved
using an DoubleNearestNeighboursExact
. The specific choice of
nearestneighbour object is controlled through the
NearestNeighboursFactory
provided to the KMeansConfiguration
used to construct instances of this class. The choice of
DoubleNearestNeighbours
affects the speed of clustering; using
approximate nearestneighbours algorithms for the KMeans can produces
comparable results to the exact KMeans algorithm in much shorter time.
The choice and configuration of DoubleNearestNeighbours
can also
control the type of distance function being used in the clustering.
The algorithm is implemented as follows: Clustering is initiated using a
DoubleKMeansInit
and is iterative. In each round, batches of
samples are assigned to centroids in parallel. The centroid assignment is
performed using the preconfigured DoubleNearestNeighbours
instances
created from the KMeansConfiguration
. Once all samples are assigned
new centroids are calculated and the next round started. Data point pushing
is performed using the same techniques as center point assignment.
This implementation is able to deal with largerthanmemory datasets by
streaming the samples from disk using an appropriate DataSource
. The
only requirement is that there is enough memory to hold all the centroids
plus working memory for the batches of samples being assigned.
Modifier and Type  Class and Description 

static class 
DoubleKMeans.Result
Result object for DoubleKMeans, extending DoubleCentroidsResult and DoubleNearestNeighboursProvider,
as well as giving access to state information from the operation of the KMeans algorithm
(i.e.

Modifier  Constructor and Description 

protected 
DoubleKMeans()
A completely default
DoubleKMeans used primarily as a convenience function for reading. 

DoubleKMeans(KMeansConfiguration<DoubleNearestNeighbours,double[]> conf)
Construct the clusterer with the the given configuration.

Modifier and Type  Method and Description 

DoubleKMeans.Result 
cluster(DataSource<double[]> ds)
Perform clustering with data from a data source.

void 
cluster(DataSource<double[]> data,
DoubleKMeans.Result result)
Main clustering algorithm.

protected DoubleKMeans.Result 
cluster(DataSource<double[]> data,
int K)
Initiate clustering with the given data and number of clusters.

DoubleKMeans.Result 
cluster(double[][] data)
Perform clustering on the given data.

void 
cluster(double[][] data,
DoubleKMeans.Result result)
Main clustering algorithm.

static DoubleKMeans 
createExact(int K)
Convenience method to quickly create an exact
DoubleKMeans . 
static DoubleKMeans 
createExact(int K,
int niters)
Convenience method to quickly create an exact
DoubleKMeans . 
static DoubleKMeans 
createKDTreeEnsemble(int K)
Convenience method to quickly create an approximate
DoubleKMeans
using an ensemble of KDTrees to perform nearestneighbour lookup. 
KMeansConfiguration<DoubleNearestNeighbours,double[]> 
getConfiguration()
Get the configuration

DoubleKMeansInit 
getInit()
Get the current initialisation algorithm

int[][] 
performClustering(double[][] data) 
protected double 
roundDouble(double value) 
protected float 
roundFloat(double value) 
protected int 
roundInt(double value) 
protected long 
roundLong(double value) 
void 
seed(long seed)
Set the seed for the internal random number generator.

void 
setConfiguration(KMeansConfiguration<DoubleNearestNeighbours,double[]> conf)
Set the configuration

void 
setInit(DoubleKMeansInit init)
Set the current initialisation algorithm

String 
toString() 
public DoubleKMeans(KMeansConfiguration<DoubleNearestNeighbours,double[]> conf)
conf
 The configuration.protected DoubleKMeans()
DoubleKMeans
used primarily as a convenience function for reading.public DoubleKMeansInit getInit()
public void setInit(DoubleKMeansInit init)
init
 the init algorithm to be usedpublic void seed(long seed)
seed
 the random seed for init random sample selection, no seed if seed < 1public DoubleKMeans.Result cluster(double[][] data)
SpatialClusterer
cluster
in interface SpatialClusterer<DoubleCentroidsResult,double[]>
data
 the data.public int[][] performClustering(double[][] data)
performClustering
in interface Clusterer<double[][]>
protected DoubleKMeans.Result cluster(DataSource<double[]> data, int K) throws Exception
#cluster(DataSource, double [][])
.data
 data source to cluster withK
 number of clusters to findException
public void cluster(double[][] data, DoubleKMeans.Result result) throws InterruptedException
result
object and as such ignores the
init object. In normal operation you should call one of the other cluster
cluster methods instead of this one. However, if you wish to resume clustering
iterations from a result that you've already generated this is the method
to use.data
 the data to be clusteredresult
 the results object to be populatedInterruptedException
 if interrupted while waiting, in
which case unfinished tasks are cancelled.public void cluster(DataSource<double[]> data, DoubleKMeans.Result result) throws InterruptedException
result
object and as such ignores the
init object. In normal operation you should call one of the other cluster
cluster methods instead of this one. However, if you wish to resume clustering
iterations from a result that you've already generated this is the method
to use.data
 the data to be clusteredresult
 the results object to be populatedInterruptedException
 if interrupted while waiting, in
which case unfinished tasks are cancelled.protected float roundFloat(double value)
protected double roundDouble(double value)
protected long roundLong(double value)
protected int roundInt(double value)
public DoubleKMeans.Result cluster(DataSource<double[]> ds)
SpatialClusterer
DataSource
could potentially be backed by disk rather in memory.cluster
in interface SpatialClusterer<DoubleCentroidsResult,double[]>
ds
 the data.public KMeansConfiguration<DoubleNearestNeighbours,double[]> getConfiguration()
public void setConfiguration(KMeansConfiguration<DoubleNearestNeighbours,double[]> conf)
conf
 the configuration to setpublic static DoubleKMeans createExact(int K)
DoubleKMeans
. All
parameters other than the number of clusters are set
at their defaults, but can be manipulated through the configuration
returned by getConfiguration()
.
Euclidean distance is used to measure the distance between points.
K
 the number of clustersDoubleKMeans
instance configured for exact kmeanspublic static DoubleKMeans createExact(int K, int niters)
DoubleKMeans
. All
parameters other than the number of clusters and number
of iterations are set at their defaults, but can be manipulated through
the configuration returned by getConfiguration()
.
Euclidean distance is used to measure the distance between points.
K
 the number of clustersniters
 maximum number of iterationsDoubleKMeans
instance configured for exact kmeanspublic static DoubleKMeans createKDTreeEnsemble(int K)
DoubleKMeans
using an ensemble of KDTrees to perform nearestneighbour lookup. All
parameters other than the number of clusters are set
at their defaults, but can be manipulated through the configuration
returned by getConfiguration()
.
Euclidean distance is used to measure the distance between points.
K
 the number of clustersDoubleKMeans
instance configured for approximate kmeans
using an ensemble of KDTrees