Package 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.

The train method will instantiate dense examples as dense vectors, speeding up the computation.

Note parallel training uses a ForkJoinPool which requires that the Tribuo codebase is given the "modifyThread" and "modifyThreadGroup" privileges when running under a SecurityManager.

See: 

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

For more on optional kmeans++ initialisation, see: 

 D. Arthur, S. Vassilvitskii.
 "K-Means++: The Advantages of Careful Seeding"
 PDF

  • Constructor Details

    • KMeansTrainer

      @Deprecated public KMeansTrainer(int centroids, int iterations, KMeansTrainer.Distance distanceType, int numThreads, long seed)
      Deprecated.
      This Constructor is deprecated in version 4.3.
      Constructs a K-Means trainer using the supplied parameters and the default random initialisation.
      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.

    • KMeansTrainer

      public KMeansTrainer(int centroids, int iterations, Distance dist, int numThreads, long seed)
      Constructs a K-Means trainer using the supplied parameters and the default random initialisation.
      Parameters:
      centroids - The number of centroids to use.
      iterations - The maximum number of iterations.
      dist - The distance function.
      numThreads - The number of threads.
      seed - The random seed.

    • KMeansTrainer

      @Deprecated public KMeansTrainer(int centroids, int iterations, KMeansTrainer.Distance distanceType, KMeansTrainer.Initialisation initialisationType, int numThreads, long seed)
      Deprecated.
      This Constructor is deprecated in version 4.3.
      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.
      initialisationType - The centroid initialization method.
      numThreads - The number of threads.
      seed - The random seed.

    • KMeansTrainer

      public KMeansTrainer(int centroids, int iterations, Distance dist, KMeansTrainer.Initialisation initialisationType, 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.
      dist - The distance function.
      initialisationType - The centroid initialization method.
      numThreads - The number of threads.
      seed - The random seed.

  • Method Details

    • postConfig

      public void postConfig()
      Used by the OLCUT configuration system, and should not be called by external code.
      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> examples, Map<String,com.oracle.labs.mlrg.olcut.provenance.Provenance> runProvenance, int invocationCount)
      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).
      invocationCount - The invocation counter that the trainer should be set to before training, which in most cases alters the state of the RNG inside this trainer. If the value is set to Trainer.INCREMENT_INVOCATION_COUNT then the invocation count is not changed.
      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.

    • setInvocationCount

      public void setInvocationCount(int invocationCount)
      Description copied from interface: Trainer
      Set the internal state of the trainer to the provided number of invocations of the train method.

      This is used when reproducing a Tribuo-trained model by setting the state of the RNG to what it was at when Tribuo trained the original model by simulating invocations of the train method. This method should ALWAYS be overridden, and the default method is purely for compatibility.

      In a future major release this default implementation will be removed.

      Specified by:
      setInvocationCount in interface Trainer<ClusterID>
      Parameters:
      invocationCount - the number of invocations of the train method to simulate

    • mStep

      protected void mStep(ForkJoinPool fjp, DenseVector[] centroidVectors, Map<Integer,List<Integer>> clusterAssignments, SGDVector[] data, double[] weights)
      Runs the mStep, writing to the centroidVectors array.

      Note in 4.2 this method changed signature slightly, and overrides of the old version will not match.

      Parameters:
      fjp - The ForkJoinPool to run the computation in if it should be executed in parallel. If the fjp is null then the computation is executed sequentially on the main thread.
      centroidVectors - The centroid vectors to write out.
      clusterAssignments - The current cluster assignments.
      data - The data points.
      weights - The example 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>