org.tribuo.clustering.kmeans

Class KMeansTrainer

java.lang.Object

org.tribuo.clustering.kmeans.KMeansTrainer

All Implemented Interfaces:

com.oracle.labs.mlrg.olcut.config.Configurable, com.oracle.labs.mlrg.olcut.provenance.Provenancable<TrainerProvenance>, Trainer<ClusterID>

public class KMeansTrainer
extends Object
implements Trainer<ClusterID>

A K-Means trainer, which generates a K-means clustering of the supplied data. The model finds the centres, and then predict needs to be called to infer the centre assignments for the input data.

It's slightly contorted to fit the Tribuo Trainer and Model API, as the cluster assignments can only be retrieved from the model after training, and require re-evaluating each example.

The Trainer has a parameterised distance function, and a selectable number of threads used in the training step. The thread pool is local to an invocation of train, so there can be multiple concurrent trainings.

See:

 J. Friedman, T. Hastie, & R. Tibshirani.
 "The Elements of Statistical Learning"
 Springer 2001. PDF
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KMeansTrainer.Distance Possible distance functions.

Field Summary

Fields inherited from interface org.tribuo.Trainer

DEFAULT_SEED

Constructor Summary

Constructors

Constructor and Description
KMeansTrainer(int centroids, int iterations, KMeansTrainer.Distance distanceType, int numThreads, long seed) Constructs a K-Means trainer using the supplied parameters.

Method Summary

Modifier and Type	Method and Description
int	getInvocationCount() The number of times this trainer instance has had it's train method invoked.
TrainerProvenance	getProvenance()
protected static DenseVector[]	initialiseCentroids(int centroids, Dataset<ClusterID> examples, ImmutableFeatureMap featureMap, SplittableRandom rng) Initialisation method called at the start of each train call.
protected void	mStep(ForkJoinPool fjp, DenseVector[] centroidVectors, Map<Integer,List<Integer>> clusterAssignments, SparseVector[] data, double[] weights)
void	postConfig()
String	toString()
KMeansModel	train(Dataset<ClusterID> dataset) Trains a predictive model using the examples in the given data set.
KMeansModel	train(Dataset<ClusterID> examples, Map<String,com.oracle.labs.mlrg.olcut.provenance.Provenance> runProvenance) Trains a predictive model using the examples in the given data set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KMeansTrainer

public KMeansTrainer(int centroids,
                     int iterations,
                     KMeansTrainer.Distance distanceType,
                     int numThreads,
                     long seed)

Constructs a K-Means trainer using the supplied parameters.

Parameters:

centroids - The number of centroids to use.

iterations - The maximum number of iterations.

distanceType - The distance function.

numThreads - The number of threads.

seed - The random seed.

Method Detail

postConfig

public void postConfig()

Specified by:

postConfig in interface com.oracle.labs.mlrg.olcut.config.Configurable

train

public KMeansModel train(Dataset<ClusterID> examples,
                         Map<String,com.oracle.labs.mlrg.olcut.provenance.Provenance> runProvenance)

Description copied from interface: Trainer

Trains a predictive model using the examples in the given data set.

Specified by:

train in interface Trainer<ClusterID>

Parameters:

examples - the data set containing the examples.

runProvenance - Training run specific provenance (e.g., fold number).

Returns:

a predictive model that can be used to generate predictions for new examples.

train

public KMeansModel train(Dataset<ClusterID> dataset)

Description copied from interface: Trainer

Trains a predictive model using the examples in the given data set.

Specified by:

train in interface Trainer<ClusterID>

Parameters:

dataset - the data set containing the examples.

Returns:

a predictive model that can be used to generate predictions for new examples.

getInvocationCount

public int getInvocationCount()

Description copied from interface: Trainer

The number of times this trainer instance has had it's train method invoked.

This is used to determine how many times the trainer's RNG has been accessed to ensure replicability in the random number stream.

Specified by:

getInvocationCount in interface Trainer<ClusterID>

Returns:

The number of train invocations.

initialiseCentroids

protected static DenseVector[] initialiseCentroids(int centroids,
                                                   Dataset<ClusterID> examples,
                                                   ImmutableFeatureMap featureMap,
                                                   SplittableRandom rng)

Initialisation method called at the start of each train call. Used to allow overriding for kmeans++, kmedoids etc.

Parameters:

centroids - The number of centroids to create.

examples - The dataset to use.

featureMap - The feature map to use for centroid sampling.

rng - The RNG to use.

Returns:

A DenseVector array of centroids.

mStep

protected void mStep(ForkJoinPool fjp,
                     DenseVector[] centroidVectors,
                     Map<Integer,List<Integer>> clusterAssignments,
                     SparseVector[] data,
                     double[] weights)

toString

public String toString()

Overrides:

toString in class Object

getProvenance

public TrainerProvenance getProvenance()

Specified by:

getProvenance in interface com.oracle.labs.mlrg.olcut.provenance.Provenancable<TrainerProvenance>