Package org.tribuo.clustering.hdbscan

Class HdbscanTrainer

java.lang.Object
org.tribuo.clustering.hdbscan.HdbscanTrainer
All Implemented Interfaces:
com.oracle.labs.mlrg.olcut.config.Configurable, com.oracle.labs.mlrg.olcut.provenance.Provenancable<TrainerProvenance>, Trainer<ClusterID>
public final class HdbscanTrainer extends Object implements Trainer<ClusterID>
An HDBSCAN* trainer which generates a hierarchical, density-based clustering representation of the supplied data.

The cluster assignments and outlier scores can be retrieved from the model after training. Outliers or noise points are assigned the label 0.

For the HDBSCAN* algorithm see: 

 R.J.G.B. Campello, D. Moulavi, A. Zimek and J. Sander "Hierarchical Density Estimates for Data Clustering,
 Visualization, and Outlier Detection", ACM Trans. on Knowledge Discovery from Data, Vol 10, 1 (July 2015), 1-51.
 HDBSCAN*

For this specific implementation and prediction technique, see: 

 G. Stewart, M. Al-Khassaweneh. "An Implementation of the HDBSCAN* Clustering Algorithm",
 Applied Sciences. 2022; 12(5):2405.
 Manuscript

  • Constructor Details

    • HdbscanTrainer

      public HdbscanTrainer(int minClusterSize)
      Constructs an HDBSCAN* trainer with only the minClusterSize parameter.
      Parameters:
      minClusterSize - The minimum number of points required to form a cluster. dist defaults to DistanceType.L2, k defaults to minClusterSize, numThreads defaults to 1 and neighboursQueryFactory defaults to NeighboursBruteForceFactory.

    • HdbscanTrainer

      @Deprecated public HdbscanTrainer(int minClusterSize, HdbscanTrainer.Distance distanceType, int k, int numThreads)
      Deprecated.
      This Constructor is deprecated in version 4.3.
      Constructs an HDBSCAN* trainer using the supplied parameters. neighboursQueryFactory defaults to NeighboursBruteForceFactory.
      Parameters:
      minClusterSize - The minimum number of points required to form a cluster.
      distanceType - The distance function.
      k - The number of nearest-neighbors to use in the initial density approximation.
      numThreads - The number of threads.

    • HdbscanTrainer

      public HdbscanTrainer(int minClusterSize, Distance dist, int k, int numThreads, NeighboursQueryFactoryType nqFactoryType)
      Constructs an HDBSCAN* trainer using the supplied parameters.
      Parameters:
      minClusterSize - The minimum number of points required to form a cluster.
      dist - The distance function.
      k - The number of nearest-neighbors to use in the initial density approximation.
      numThreads - The number of threads.
      nqFactoryType - The nearest neighbour query implementation factory to use.

    • HdbscanTrainer

      public HdbscanTrainer(int minClusterSize, int k, NeighboursQueryFactory neighboursQueryFactory)
      Constructs an HDBSCAN* trainer using the supplied parameters.
      Parameters:
      minClusterSize - The minimum number of points required to form a cluster.
      k - The number of nearest-neighbors to use in the initial density approximation.
      neighboursQueryFactory - The nearest neighbour query implementation factory to use.

  • 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 HdbscanModel 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 HdbscanModel 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 newInvocationCount)
      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:
      newInvocationCount - the number of invocations of the train method to simulate

    • 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>